// packages/core — 입력 인텔리전스 도메인 정본. // // 두 가지를 담는다: // 1) 입력 텔레메트리 계약 (키스트로크 분류 · 집계 버킷 · 타이핑 타) // 2) 다음 문장 제안 정책 (언제 요청하고 언제 지우는지, 후보 정제/랭킹) // // 설계 근거 (뇌피셜 금지 — 조사 결과를 그대로 따른다): // - 수집 항목·집계 방식은 ActivityWatch `aw-watcher-input`(presses/clicks/deltaX/deltaY/ // scrollX/scrollY, 5초 heartbeat, 키 내용 미저장)을 따른다. // - 다음 문장 제안의 디바운스/취소/출력 토큰 한도는 인라인 컴플리션 실측값 // (Continue 350ms, Tabby 250ms adaptive, twinny 300ms, Zed p50<200ms p90<500ms, // Tabby max_decoding_tokens=64, KeyType max 4~16)을 기본값으로 반영한다. // - 커서 rect 폴백 순서(케어렛 → 포커스 요소 → 마우스)는 KeyType.Windows 의 // CaretGeometryQuality.Estimated 경로와 같다. // // 순수 함수만 둔다 — Electron/Node 의존 금지 (테스트 가능성 유지). // // 후보 텍스트 정제는 suggestion-text.ts, 터미널 입력 줄 파싱은 terminal-prompt.ts 가 // 정본이다. 기존 import 경로(@d3ro/core/input-intelligence)를 유지하려고 여기서 다시 export 한다. import { SENTENCE_TERMINATORS, SUGGESTION_MAX_OUTPUT_CHARS, normalizeRequestPrefix, normalizeSessionPrefix, type SuggestionJoint } from './suggestion-text' import { NON_PROSE_GLYPH_PATTERN } from './terminal-prompt' import type { AnchorKind, PhysicalRect } from './popup-placement' import { countLexicalWords } from './text-segmentation' import { extractTerms } from './personal-graph' export { SUGGESTION_CONTEXT_MAX_CHARS, SUGGESTION_MAX_OUTPUT_CHARS, buildLocalSuggestionCandidateEntries, buildLocalSuggestionCandidates, containsEmoji, endsSentence, extractContinuation, joinSuggestion, normalizeRequestPrefix, normalizeSessionPrefix, normalizeSuggestionText, parseSuggestionCandidates, sanitizeSuggestionLine, stripModelArtifacts } from './suggestion-text' export type { ContinuationOptions, ExtractedContinuation, LocalSuggestionCandidate, LocalSuggestionHints, SuggestionJoint } from './suggestion-text' export { TerminalKeystrokeTracker, composeHangul2Set, extractTerminalActiveContext, extractTerminalPromptPrefix, vkToPrintableChar } from './terminal-prompt' export type { TerminalActiveContext, TerminalKeyInput, TerminalVimMode } from './terminal-prompt' // ============================================================ // 기하 — 정본은 popup-placement.ts (좌표 공간 · 배치 정책). 기존 import 경로를 유지한다. // ============================================================ export { anchorFloatingPanel, anchorFloatingPanelInDips, asDipPoint, asDipRect } from './popup-placement' export type { AnchorKind, DipPoint, DipRect, PhysicalRect, ScreenGeometryPort, UiRect } from './popup-placement' /** 마우스 이동 누적 전에 무시할 최소 이동량(px). 미세抖动 노이즈 제거. */ export const MOUSE_MOVE_NOISE_FLOOR_PX = 2 /** 맨해튼 거리 — ActivityWatch 와 동일하게 축별 절대값 합을 쓴다. */ export function manhattanDistance(from: { x: number; y: number }, to: { x: number; y: number }): number { return Math.abs(to.x - from.x) + Math.abs(to.y - from.y) } // ============================================================ // 키스트로크 분류 (내용이 아니라 '종류'만 남긴다) // ============================================================ export type KeyStrokeClass = | 'letter' | 'digit' | 'symbol' | 'space' | 'enter' | 'tab' | 'backspace' | 'delete' | 'arrow' | 'navigation' | 'function' | 'modifier' | 'shortcut' | 'ime' | 'other' /** Windows VK 코드 → 키 종류. 키 자체는 저장하지 않는다. */ export function classifyKeyStroke( code: number, modifiers: { ctrl: boolean; alt: boolean; meta: boolean } ): KeyStrokeClass { if (code >= 0xa0 && code <= 0xa5) return 'modifier' if (code === 0x5b || code === 0x5c || code === 0x10 || code === 0x11 || code === 0x12) return 'modifier' if (modifiers.ctrl || modifiers.alt || modifiers.meta) return 'shortcut' if (code >= 0x41 && code <= 0x5a) return 'letter' if (code >= 0x30 && code <= 0x39) return 'digit' if (code >= 0x60 && code <= 0x69) return 'digit' if (code === 0x20) return 'space' if (code === 0x0d) return 'enter' if (code === 0x09) return 'tab' if (code === 0x08) return 'backspace' if (code === 0x2e) return 'delete' if (code >= 0x25 && code <= 0x28) return 'arrow' if (code >= 0x21 && code <= 0x24) return 'navigation' if (code >= 0x70 && code <= 0x87) return 'function' if (code === 0x1b) return 'navigation' if (code >= 0xba && code <= 0xc0) return 'symbol' if (code >= 0xdb && code <= 0xde) return 'symbol' if (code === 0xbe || code === 0xbc || code === 0xbd) return 'symbol' if (code === 0xe5) return 'ime' return 'other' } /** 단어 경계로 볼 수 있는 키 종류인지 (단어 수 추정용 보조 지표). */ export function isWordBoundaryKey(keyClass: KeyStrokeClass): boolean { return keyClass === 'space' || keyClass === 'enter' || keyClass === 'tab' } // ============================================================ // 스트 지표 // ============================================================ /** * 단어 수. * * 공백 분리 언어(한국어·라틴 문자 등)는 공백 분리 토큰 중 문자/숫자를 포함한 것만 세고, * 띄어쓰기 없이 쓰는 문자 체계(중국어·일본어·태국어 등)는 `countLexicalWords`(Intl.Segmenter * 또는 글자 수 어림)로 분할해 과소 집계를 방지한다. */ export function countWords(text: string): number { return countLexicalWords(text) } /** 문장 수 — 종결 부호 + 개행 기준. */ export function countSentences(text: string): number { if (!text) return 0 let count = 0 for (const char of text) { if (SENTENCE_TERMINATORS.test(char) || char === '\n') count += 1 } return count } /** 케어 앞 텍스트만 잘라낸다 (UIA 스냅샷 → 컨텍스트). */ export function textBeforeCaret(text: string, caretOffset: number | null): string { if (caretOffset === null || caretOffset < 0) return text return text.slice(0, Math.min(caretOffset, text.length)) } // ============================================================ // 타이핑 델타 (UIA 스냅샷 diff — IME 커밋 텍스트까지 반영된다) // ============================================================ export interface TypedDelta { insertedChars: number insertedWords: number insertedSentences: number /** 학습이 켜져 있을 때만 실제 삽입 텍스트를 담는다 */ insertedText: string /** 필드 전환/붙여넣기로 판단해 통계에서 제외했는지 */ replaced: boolean } /** 이 길이를 넘는 삽입은 타이핑이 아니라 붙여넣기/필드 전환으로 본다. */ export const PASTE_INSERTION_THRESHOLD_CHARS = 200 /** * 두 UIA 스냅샷의 최장 공통 접두/접미 diff 로 "새로 입력된 구간"을 뽑는다. * * 키코드로 텍스트를 복원하지 않는 이유: 한/일 IME 는 물리 키가 아니라 조합 결과가 * 텍스트가 되므로 키코드 재구성은 원리적으로 불가능하다. 커밋된 텍스트를 읽어 * diff 하는 방식만이 CJK 를 포함해 정확하다. */ /** * 두 텍스트 사이의 편집이 문서 끝에서 일어났는가 (케어렛을 모를 때 "커서 = 문서 끝" 가정의 근거). * * computeTypedDelta 와 같은 공통 접두/접미 분해를 쓴다. 바뀐 구간 뒤에 남은 공통 접미가 없으면 * 끝에서 쓰거나 지운 것이다. 같으면(편집 없음) true. */ export function isEditAtTextEnd(prevRaw: string, nextRaw: string): boolean { // RichEdit 계열(카카오톡 등)은 값 끝에 줄끝 문자(\r)를 붙여 돌려주고, 한영 자동 전환 직후에는 // 교체 전후 텍스트가 모두 공백("dkssud " → "안녕 ")으로 끝난다. 끝 공백·줄끝 문자를 그대로 비교하면 // 마지막 글자(' ')가 같아 중간 편집으로 오인하고 caret-unknown 으로 막힌다(실측 2026-10-03·2026-10-26). const prevText = prevRaw.replace(/[\s\u200b\ufeff]+$/u, '') const nextText = nextRaw.replace(/[\s\u200b\ufeff]+$/u, '') if (prevText === nextText) return true let prefix = 0 const maxPrefix = Math.min(prevText.length, nextText.length) while (prefix < maxPrefix && prevText[prefix] === nextText[prefix]) prefix += 1 const maxSuffix = Math.min(prevText.length - prefix, nextText.length - prefix) // 공통 접미가 한 글자라도 남으면 편집 지점 뒤에 기존 텍스트가 있다 — 문서 중간 편집이다. if (maxSuffix <= 0) return true return prevText[prevText.length - 1] !== nextText[nextText.length - 1] } export function computeTypedDelta( prevText: string, nextText: string, options: { keepText: boolean } ): TypedDelta { const empty: TypedDelta = { insertedChars: 0, insertedWords: 0, insertedSentences: 0, insertedText: '', replaced: false } if (!nextText) return { ...empty } if (nextText === prevText) return { ...empty } let prefix = 0 const maxPrefix = Math.min(prevText.length, nextText.length) while (prefix < maxPrefix && prevText[prefix] === nextText[prefix]) prefix += 1 let suffix = 0 const maxSuffix = Math.min(prevText.length - prefix, nextText.length - prefix) while ( suffix < maxSuffix && prevText[prevText.length - 1 - suffix] === nextText[nextText.length - 1 - suffix] ) { suffix += 1 } const inserted = nextText.slice(prefix, nextText.length - suffix) if (!inserted) return { ...empty } if (inserted.length > PASTE_INSERTION_THRESHOLD_CHARS) { return { ...empty, replaced: true } } return { insertedChars: inserted.length, insertedWords: countWords(inserted), insertedSentences: countSentences(inserted), insertedText: options.keepText ? inserted : '', replaced: false } } // ============================================================ // UIA 포커스 스냅샷 // ============================================================ export type FocusTextSource = 'value' | 'text' | 'legacy' | 'none' /** * 포커스된 입력 요소의 스냅샷. * * `available === false` 는 "지 못했다"는 뜻이고, 이때는 텍스트/케어렛을 쓰지 않는다 * (fail-closed). `isPassword` 는 UIA `IsPassword` 프로퍼티(30019) 결과다. */ export interface FocusSnapshot { available: boolean /** 사용 불가 사유 (진단용) */ reason?: string isPassword: boolean isEditable: boolean /** IME 조합 진행 중 — 조합 중에는 제안을 요청하지 않는다 */ isComposing: boolean /** 비축소 텍스트 선택이 있으면 제안을 표시하지 않는다. */ hasSelection: boolean controlType?: string controlName?: string className?: string textSource: FocusTextSource text: string caretOffset: number | null /** 물리 픽셀 (UIA 는 DPI-aware 로 동작한다) — 배치 전에 ScreenGeometryPort 로 DIP 변환 */ caretRect: PhysicalRect | null elementRect: PhysicalRect | null windowTitle: string | null appName: string | null processId: number | null capturedAt: number } export function emptyFocusSnapshot(reason: string, now: number): FocusSnapshot { return { available: false, reason, isPassword: false, isEditable: false, isComposing: false, hasSelection: false, textSource: 'none', text: '', caretOffset: null, caretRect: null, elementRect: null, windowTitle: null, appName: null, processId: null, capturedAt: now } } // ============================================================ // 텔레메트리 상태 (렌더러/프리로드와 공유하는 계약) // ============================================================ /** 마지막 입력 스냅샷 요약 — UI 가 "왜 제안이 안 뜨는지" 를 보여주는 근거. */ export interface InputSnapshotSummary { at: number appName: string | null windowTitle: string | null editable: boolean isPassword: boolean composing: boolean textSource: string textLength: number /** 케어렛 오프셋이 없어 문서 tail 을 접두로 쓴 경우 */ caretFallback: boolean } /** * 입력 텔레메트리 수집 상태. * * main 서비스가 만들고 렌더러 설정 화면이 읽는다. 계약이므로 core 에 둔다 * (렌더러는 main 모듈을 import 할 수 없다). */ export interface InputTelemetryState { enabled: boolean paused: boolean running: boolean learnTypedText: boolean excludedApps: string[] appName: string | null windowTitle: string | null /** UIA 브리지 상태 (진단용) */ bridgeReason: string bridgeAvailable: boolean lastSnapshotAt: number /** 마지막 스냅샷 요약 (없으면 null) */ lastSnapshot: InputSnapshotSummary | null /** 반복적으로 읽을 수 없는 앱을 발견했을 때만 제안한다. */ exclusionRecommendation: InputExclusionRecommendation | null } export interface AppReadabilityEvidence { appName: string | null samples: number readable: number unreadable: number empty: number } export interface InputExclusionRecommendation { appName: string reason: 'repeated-unreadable' | 'repeated-empty' samples: number } /** 반복적으로 읽히지 않는 앱만 제외 후보로 제안한다. */ export function recommendAppExclusion( evidence: AppReadabilityEvidence, minSamples = 4 ): InputExclusionRecommendation | null { const appName = evidence.appName?.trim() const samples = Math.max(0, evidence.samples) const requiredSamples = Math.max(1, minSamples) const readable = Math.max(0, evidence.readable) const unreadable = Math.max(0, evidence.unreadable) const empty = Math.max(0, evidence.empty) const problematicRatio = samples === 0 ? 0 : (unreadable + empty) / samples if (!appName || samples < requiredSamples || readable > 0 || problematicRatio < 0.75) return null return { appName, reason: unreadable >= empty ? 'repeated-unreadable' : 'repeated-empty', samples } } // ============================================================ // 제안 정책 // ============================================================ export type SuggestionSkipReason = | 'disabled' | 'not-editable' | 'password-field' | 'composing' | 'selection-active' | 'excluded-app' | 'empty-prefix' | 'sentence-complete' | 'prefix-too-short' | 'debounce' | 'rate-limited' | 'budget-exhausted' | 'model-unavailable' | 'already-visible' /** 사용자가 명시적으로 닫았다 */ | 'dismissed' /** 제안을 수락해 삽입했다 */ | 'accepted' /** 제안 후 사용자가 텍스트를 바꿔 더 이상 유효하지 않다 */ | 'stale' /** 생성 실패/결과 없음 */ | 'generation-failed' /** 같은 텍스트로 이미 요청했다 (클릭만 했거나 엔터로 보낸 뒤 재요청 방지) */ | 'unchanged' /** 연속 실패 후 쿨다운 중 (모델이 다른 작업으로 바쁠 수 있다) */ | 'cooldown' /** 포커스만 옮겨 왔을 뿐 이 필드에서 실제로 타이핑하지 않았다 (마우스 클릭 등) */ | 'not-typing' /** * 케어렛 위치를 알 수 없고(예: Notepad — ValuePattern 만 제공) 마지막 편집도 문서 끝이 아니었다. * 접두가 "문서 끝" 이라 실제 커서 위치와 무관하다 — 수락하면 문서 중간에 엉뚱한 문장이 붙는다. */ | 'caret-unknown' /** 주소·경로·쿼리를 치는 중 — 문장을 이어 쓸 자리가 아니다 */ | 'address-input' export type SuggestionDecision = | { action: 'request'; prefix: string } | { action: 'skip'; reason: SuggestionSkipReason } | { action: 'clear'; reason: SuggestionSkipReason } export type SuggestionRefreshDecision = 'keep' | 'regenerate' | 'stale' export interface SuggestionPolicyInput { enabled: boolean modelAvailable: boolean overlayVisible: boolean composing: boolean hasSelection: boolean isPassword: boolean isEditable: boolean appName: string | null excludedApps: readonly string[] /** 포커스가 바뀐 뒤 이 필드에서 실제로 편집이 있었는가 (마우스로 필드에 들어오기만 한 경우 false) */ editedSinceFocus: boolean /** 최근에 실제로 타이핑했는가 (recentTypingWindowMs 이내) */ typedRecently: boolean /** 어렛 앞 스트 */ prefix: string /** * prefix 가 실제 커서 앞 텍스트라고 믿을 수 있는가. 케어렛 오프셋을 알면 true, 모르면 * 마지막 편집이 문서 끝에서 일어났을 때만 true. 생략하면 true(호환). */ caretReliable?: boolean idleMs: number triggerDelayMs: number minPrefixChars: number sinceLastRequestMs: number minIntervalMs: number requestsThisMinute: number maxRequestsPerMinute: number requestsToday: number dailyBudget: number } /** * 제안 요청/스킵/삭제 결정. * * 순서가 중요하다: 비활성·보안(비밀번호)·IME 조합은 다른 어떤 조건보다 먼저 차단한다. * `clear` 는 "오버레이를 지워야 한다"는 뜻이고, `skip` 은 "이번엔 넘어간다"이다. */ /** * 커서 앞 마지막 덩어리(공백 없는 토큰)가 주소·경로·쿼리인가. * "https://…", "www.…", "example.com/…", "D:/work/…", "?utm_source=…" 처럼 생겼으면 그렇다. * 한글 문장 속 "1/2" 같은 짧은 것은 아니다(점·슬래시 구조가 있어야 한다). */ export function isAddressInput(prefix: string): boolean { if (/\s$/u.test(prefix)) return false const token = prefix.split(/\s+/u).pop() ?? '' if (token.length < 4) return false if (/^(https?:\/\/|www\.|file:)/iu.test(token) || token.includes('://')) return true if (/^[a-z0-9-]+(\.[a-z0-9-]+)+(\/|$|\?|#|:)/iu.test(token) && /\.[a-z]{2,}/iu.test(token)) return true if (/^[a-z]:[\\/]/iu.test(token) || /^\.{0,2}\//u.test(token)) return true return /[?&][\w.-]+=/u.test(token) } export function decideSuggestion(input: SuggestionPolicyInput): SuggestionDecision { if (!input.enabled) return { action: 'clear', reason: 'disabled' } if (input.isPassword) return { action: 'clear', reason: 'password-field' } if (input.hasSelection) return { action: 'clear', reason: 'selection-active' } if (!input.isEditable) return { action: 'clear', reason: 'not-editable' } if (input.appName && isAppExcluded(input.appName, input.excludedApps)) { return { action: 'clear', reason: 'excluded-app' } } // 케어렛을 모르는 필드에서 문서 중간을 고쳤다 — 접두(문서 끝)가 커서 위치와 무관하다. // 떠 있는 세션도 닫는다: 수락하면 실제 커서(문서 중간)에 문서 끝의 이어 쓰기가 붙는다. if (input.caretReliable === false) return { action: 'clear', reason: 'caret-unknown' } // 포커스만 옮겨 왔을 뿐(마우스 클릭 등) 이 필드에서 아무것도 치지 않았으면 제안하지 않는다. // // 유휴 판정이 키보드 기준이라, 필드에 이미 차 있던 텍스트로 클릭만 해도 (마지막 // 키 입력이 오래전이라) idleMs 조건을 통과해 제안이 뜨던 문제(실측: YouTube 검색창 // 클릭만 했는데 옛 검색어로 제안이 뜸). // // 단, 이미 떠 있는 제안은 지우지 않는다. 사용자가 타이핑을 멈추는 순간은 바로 // 후보를 읽고 고르는 순간이다 — 여기서 지우면 클릭·단축키 수락이 받을 후보가 // 없어 "골라도 안 들어가는" 상태가 된다(실측 2026-09-27: 후보 표시 2초 뒤 // not-typing 으로 닫힘). 새 요청만 막는다. if (!input.editedSinceFocus || !input.typedRecently) { if (input.overlayVisible) return { action: 'skip', reason: 'already-visible' } return { action: 'clear', reason: 'not-typing' } } const prefix = normalizeRequestPrefix(input.prefix) if (!prefix) return { action: 'clear', reason: 'empty-prefix' } // 주소창·경로 입력 중에는 문장을 제안하지 않는다(실측: "haramlog.app/ja/beta" 에 고객센터식 문장 12개). if (isAddressInput(input.prefix)) return { action: 'clear', reason: 'address-input' } // 문장이 끝났다고 막지 않는다. // // 이 기능은 "다음 문장 제안" 이다 — 마침표/물음표 뒤야말로 다음 문장이 필요한 // 지점이고, 채팅에서는 문장을 이어 쓰는 것이 정상이다. 처음에는 종결 부호를 // 차단 사유로 뒀는데, 실측 로그(Discord)에서 sentence-complete 가 모든 시도를 // 막아 "한 번도 안 뜨는" 결과가 됐다. if (prefix.length < input.minPrefixChars) return { action: 'clear', reason: 'prefix-too-short' } if (input.overlayVisible) return { action: 'skip', reason: 'already-visible' } // IME 조합 중에는 더 오래 기다린다. // // 조합을 하드 차단하면 한국어/일본어에서 기능이 죽는다 — 이핑 대부분이 조합 안에서 // 일어나므로 매 스냅샷이 조합 중으로 잡혀 영원히 제안이 안 나온다(실측 로그: // comp=true 반복 → "딱 한 번 나오고 이후 안 나옴"). 대신 조합 중에는 트리거 // 지연을 배수로 늘려, 타이핑이 이어지는 동안에는 조용하고 손을 멈춘 순간에만 // 제안을 만든다. const requiredIdle = input.composing ? input.triggerDelayMs * COMPOSING_IDLE_MULTIPLIER : input.triggerDelayMs if (input.idleMs < requiredIdle) { return { action: 'skip', reason: input.composing ? 'composing' : 'debounce' } } if (!input.modelAvailable) return { action: 'skip', reason: 'model-unavailable' } if (input.sinceLastRequestMs < input.minIntervalMs) return { action: 'skip', reason: 'rate-limited' } if (input.requestsThisMinute >= input.maxRequestsPerMinute) { return { action: 'skip', reason: 'rate-limited' } } if (input.requestsToday >= input.dailyBudget) return { action: 'skip', reason: 'budget-exhausted' } return { action: 'request', prefix } } /** * 생성 접두가 현재 접두의 연속 확장인지 판정한다. * * 마지막 글자는 아직 조합 중인 IME 음절일 수 있어, 그 한 글자를 뺀 접두까지도 * 연속 확장으로 인정한다 (예: 생성 시점 "하" → 현재 "한"). */ export function extendsPrefix(generatedPrefix: string, currentPrefix: string): boolean { const generated = normalizeRequestPrefix(generatedPrefix) const current = normalizeRequestPrefix(currentPrefix) if (current.startsWith(generated)) return true return generated.length > 0 && current.startsWith(generated.slice(0, -1)) } /** * 표시 중인 제안 세션(페이지 넘기며 보는 후보 목록)이 여전히 이 접두에 유효한지. * * `extendsPrefix` 와 달리 성장(이어 치기)은 허용하지 않는다 — "다음 문장이 시작됐다" * 는 곧 세션 종료다(설계). 마지막 글자만 IME 조합으로 바뀐 경우만 예외로 둔다 * (생성 시점 "하" → 지금 "한": 길이는 같고 마지막 글자만 다르다). * * 세션은 마지막 SUGGESTION_CONTEXT_MAX_CHARS 자로 만든 후보이므로 양쪽 모두 * normalizeSessionPrefix 로 맞춘 뒤 비교한다 — 한쪽만 자르면 400자를 넘는 입력창에서 * 텍스트가 그대로여도 세션이 stale 로 닫힌다. */ export function matchesSessionPrefix(generatedPrefix: string, currentPrefix: string): boolean { const generated = normalizeSessionPrefix(generatedPrefix) const current = normalizeSessionPrefix(currentPrefix) if (current === generated) return true if (generated.length === 0) return false return current.length === generated.length && current.slice(0, -1) === generated.slice(0, -1) } /** * 진행 중인 생성(아직 후보 없음)을 계속 둘지 결정한다 — 세션 규칙과 같은 기준이다. * * 결과는 요청한 접두로 게시되고, 게시된 세션은 성장을 허용하지 않는다(matchesSessionPrefix). * 그래서 요청 뒤 사용자가 몇 글자라도 더 쳤다면 결과는 도착하자마자 stale 로 닫힌다 — * 깜빡임 · 버려지는 모델/채우기 요청 · 옛 접두용 문장 수락을 막으려면 그 즉시 취소한다. * IME 마지막 글자 조합 변화만 예외다. */ export function decideInFlightGeneration(requestedPrefix: string, currentPrefix: string): 'keep' | 'stale' { return matchesSessionPrefix(requestedPrefix, currentPrefix) ? 'keep' : 'stale' } /** * 표시 중인 제안을 계속 둘지, 새로 만들지, 즉시 버릴지 결정한다. * * 현재 접두가 생성 접두의 연속 확장이 아니면 이미 표시된 후보는 다른 문맥의 * 결과이므로 stale 이다. 연속 확장도 일정량 이상일 때만 재생성해 입력 중인 * 로컬 모델 요청이 반복되는 것을 막는다. */ export function decideSuggestionRefresh( generatedPrefix: string, currentPrefix: string, minimumGrowth = SUGGESTION_DEFAULTS.regenerateAfterChars ): SuggestionRefreshDecision { const generated = normalizeRequestPrefix(generatedPrefix) const current = normalizeRequestPrefix(currentPrefix) if (!generated) return 'regenerate' if (!extendsPrefix(generated, current)) return 'stale' return current.length - generated.length >= minimumGrowth ? 'regenerate' : 'keep' } /** * 한 번의 입력 문맥에 대해 제안 서비스가 할 일 (판별 합집합). * * - `end-session`: 표시 중인 세션의 접두가 어긋났다 — 세션을 stale 로 닫는다. * - `generate`: 모델 생성을 시작한다. * - `settle`: 생성하지 않는다. `reason` 을 남기고, `tryLocalMemory` 면 로컬 기억 후보를 * 먼저 게시해 보고, 게시하지 못하면 `then` 을 수행한다. */ export type SuggestionStep = | { action: 'end-session'; reason: 'stale' } | { action: 'generate'; prefix: string } | { action: 'settle' reason: SuggestionSkipReason tryLocalMemory: boolean /** * record: 사유만 남긴다. dismiss: 표시 중이면 이 사유로 닫는다. * show-warming: "준비 중" 을 보여준다. warm-up: 워밍업을 시작하고 "준비 중" 을 보여준다. */ then: 'record' | 'dismiss' | 'show-warming' | 'warm-up' } export interface SuggestionStepInput { /** 정책 입력. overlayVisible 은 "생성/워밍업/후보 표시 중" 전체를 뜻한다. */ policy: SuggestionPolicyInput /** 후보 세션이 화면에 떠 있는가 (후보 1개 이상) */ sessionVisible: boolean /** 세션을 만든 접두 */ sessionPrefix: string /** 연속 실패 쿨다운 중인가 */ coolingDown: boolean /** 사용자가 X 로 닫은 직후의 조용한 구간인가 */ userDismissedQuiet: boolean /** 마지막으로 모델에 실제 요청한 접두 (normalizeRequestPrefix 적용) */ lastRequestedPrefix: string /** 지금 쓸 모델이 메모리에 떠 있다고 볼 수 있는가 */ modelWarm: boolean /** 직전 워밍업이 실패해 재시도를 잠시 미루는 중인가 */ warmUpBackoff: boolean /** * 모델 서버를 실제로 준비하는 작업(워밍업 루프)이 진행 중인가. * * 서버가 없을 때(model-unavailable) "준비 중" 은 이 작업이 있을 때만 보여준다 — 아무것도 * 준비하지 않는데 스피너를 띄우면 끝나지 않는 "준비 중" 이 옛 캐럿 위에 20초씩 반복된다 * (Ollama 미설치/중지). 생략하면 예전처럼 "준비 중" 을 보여준다(호환). 서비스는 항상 넘긴다. */ modelStarting?: boolean } /** * 제안 서비스의 판단 순서 정본: 세션 유효성 → 쿨다운 → 사용자 닫기 → 정책 → 모델 온기. * * 서비스는 이 결과를 실행만 한다. 쿨다운 경로도 decideSuggestion 의 'already-visible' * 규칙을 거친다 — 쿨다운 중 표시된 로컬 기억 세션을 매 스냅샷마다 다시 만들거나 * (선택 초기화 · 이력 중복) 닫지 않는다. */ export function decideSuggestionStep(input: SuggestionStepInput): SuggestionStep { const { policy } = input if (input.sessionVisible && !matchesSessionPrefix(input.sessionPrefix, policy.prefix)) { return { action: 'end-session', reason: 'stale' } } // 로컬 기억은 모델과 무관하다 — 같은 정책을 "모델 있음 · 표시 없음" 으로 평가한다. const localMemoryAllowed = decideSuggestion({ ...policy, modelAvailable: true, overlayVisible: false }).action === 'request' if (input.coolingDown) { const presentation = decideSuggestion({ ...policy, modelAvailable: true }) if (presentation.action === 'skip' && presentation.reason === 'already-visible') { return { action: 'settle', reason: 'cooldown', tryLocalMemory: false, then: 'record' } } return { action: 'settle', reason: 'cooldown', tryLocalMemory: localMemoryAllowed, then: 'dismiss' } } if (input.userDismissedQuiet) { return { action: 'settle', reason: 'cooldown', tryLocalMemory: false, then: 'record' } } const decision = decideSuggestion(policy) if (decision.action === 'clear') { return { action: 'settle', reason: decision.reason, tryLocalMemory: false, then: 'dismiss' } } if (decision.action === 'skip') { // 같은 텍스트로 이미 요청했다면 다시 만들지 않는다 (클릭만 했거나, 엔터로 보낸 뒤 // UIA 가 옛 텍스트를 돌려줄 때 제안이 반복 생성되던 문제). const current = normalizeRequestPrefix(policy.prefix) if (input.lastRequestedPrefix && current === input.lastRequestedPrefix) { return { action: 'settle', reason: 'unchanged', tryLocalMemory: false, then: 'record' } } if (decision.reason === 'model-unavailable') { return { action: 'settle', reason: 'model-unavailable', tryLocalMemory: localMemoryAllowed, // 준비 작업이 없으면 기능은 꺼진 것처럼 조용해야 한다 (설정 문구: "제안이 꺼진 상태로 동작"). then: input.modelStarting === false ? 'record' : 'show-warming' } } return { action: 'settle', reason: decision.reason, tryLocalMemory: false, then: 'record' } } // 모델이 유휴로 내려갔을 것으로 보이면 생성 대신 워밍업부터 한다 — 콜드 리로드는 // 요청 타임아웃보다 길어 그대로 요청하면 항상 시간 초과한다. if (!input.modelWarm) { if (input.warmUpBackoff) { return { action: 'settle', reason: 'generation-failed', tryLocalMemory: localMemoryAllowed, then: 'record' } } return { action: 'settle', reason: 'model-unavailable', tryLocalMemory: localMemoryAllowed, then: 'warm-up' } } return { action: 'generate', prefix: decision.prefix } } /** 제외 앱 판정 — 대소문자 무시, 실행 파일명(확장자 무관) 부분 일치. */ export function isAppExcluded(appName: string, excludedApps: readonly string[]): boolean { const target = appName.trim().toLowerCase() if (!target) return false const base = target.replace(/\.exe$/u, '') for (const raw of excludedApps) { const entry = raw.trim().toLowerCase().replace(/\.exe$/u, '') if (!entry) continue if (target === entry || base === entry) return true } return false } /** * 터미널 — 화면 버퍼가 곧 "입력창" 으로 읽혀 상태줄·명령·출력이 친 글로 잡힌다 * (실측: Claude Code 상태줄 `◑ OPUS 5`, `5 medium │ CTX ▕░░▏` 가 학습됨). * 그래서 학습에서는 뺀다. 제안은 화면에서 입력 줄만 골라 쓴다(extractTerminalPromptPrefix). */ export const TERMINAL_APPS: readonly string[] = Object.freeze([ 'WindowsTerminal', 'wt', 'OpenConsole', 'conhost', 'cmd', 'powershell', 'pwsh', 'mintty', 'alacritty', 'wezterm', 'wezterm-gui', 'kitty', 'ghostty', 'putty', 'MobaXterm', 'Kitedesk', 'nvim-qt', 'neovide', 'gvim', 'Hyper', 'Tabby', 'Warp' ]) export function isTerminalApp(appName: string | null | undefined): boolean { return !!appName && isAppExcluded(appName, TERMINAL_APPS) } /** * 학습에서 빼는 앱 — 터미널 + 코드 에디터 + 코딩 에이전트 허브. * * 개인 문구 코퍼스는 사용자의 자연어 문체를 배우는 곳이다. 코드와 에이전트에게 * 보낸 개발 지시가 섞이면 카카오톡에서도 개발 문장이 제안된다(실측: 코퍼스 138개 중 * 대부분이 터미널·Agent Switchboard 발). 제안 자체는 에디터/에이전트에서도 허용한다. */ export const LEARNING_EXCLUDED_APPS: readonly string[] = Object.freeze([ ...TERMINAL_APPS, 'Code', 'Code - Insiders', 'Cursor', 'Windsurf', 'Antigravity', 'Zed', 'devenv', 'idea64', 'pycharm64', 'webstorm64', 'rider64', 'clion64', 'goland64', 'studio64', 'sublime_text' ]) /** * 그 앱 안에서만 배우는 앱 — 표본(typing_samples)에만 앱 이름과 함께 저장하고, 공용 문구·그래프에는 넣지 않는다. * 제안할 때는 같은 앱의 표본에서만 이어 쓴 글을 찾는다. * * Agent Switchboard 는 사용자가 가장 많이 타이핑하는 곳인데(2026-10-25), 2026-09-24 에 학습 제외였다 — 개발 지시가 * 카카오톡 제안으로 번졌기 때문. 앱 안으로 가두면 번지지 않으면서 그 앱의 제안에는 재료가 생긴다. */ export const APP_SCOPED_LEARNING_APPS: readonly string[] = Object.freeze(['Agent Switchboard']) /** 이 앱의 글은 그 앱 안에서만 쓰는가 (공용 문구·그래프 금지). */ export function isAppScopedLearning(appName: string | null | undefined): boolean { return !!appName && isAppExcluded(appName, APP_SCOPED_LEARNING_APPS) } /** * 제안 이력에 입력 문맥(접두) 원문을 남겨도 되는가. * * 접두는 사용자가 친 글 그 자체다 — 학습 동의(inputLearnTypedText)가 있고, 학습 제외 앱 * (터미널·에디터·에이전트 허브)이 아닐 때만 저장한다. 텔레메트리 학습과 같은 규칙을 쓴다. * 그 밖에는 원문 대신 빈 문자열을 남겨 이력 개수·수락률 통계만 유지한다. */ export function shouldPersistSuggestionPrefix(input: { learnTypedText: boolean appName: string | null }): boolean { if (!input.learnTypedText) return false return shouldLearnFromApp(input.appName) } /** * 이 앱에서 나온 텍스트를 개인 코퍼스(문구·그래프·표본)에 넣어도 되는가 — 학습 제외 앱의 정본. * * 출처(타이핑·받아쓰기·수락한 제안)와 무관하다: 터미널·에디터·에이전트 허브에 보낸 개발 지시는 * 어떤 경로로 들어왔든 KakaoTalk 제안으로 새면 안 된다. 앱을 모르면(null) 학습한다. */ export function shouldLearnFromApp(appName: string | null | undefined): boolean { return !(appName && isAppExcluded(appName, LEARNING_EXCLUDED_APPS)) } /** * 터미널·코드 에디터·에이전트 허브(예: Integrated Terminal 이나 캔버스 터미널이 들어 있는 개발 도구)인가. * * 이 표면에서는: * 1) 일반 철자·모델 오타 교정은 끄고 한영 자판 전환(layoutOnly)만 수행하며, * 2) UIA 가 텍스트를 돌려주지 않는 캔버스 영역(xterm.js, Kitedesk 등)에서도 키스트로크 추적으로 * 한영 자판 자동 전환과 Vim 모드 전환을 지원한다. */ export function isTerminalOrDeveloperSurface(appName: string | null | undefined): boolean { if (!appName) return false return isTerminalApp(appName) || !shouldLearnFromApp(appName) || isAppScopedLearning(appName) } /** * xterm.js 기반 임베디드 터미널(Agent Switchboard, VS Code, Cursor, Hyper, Tabby 등)의 숨은 입력창인가. * * `