ummaya 0.2.3 → 0.2.4

package/tui/src/tools/_shared/locationInputRepair.ts

@@ -0,0 +1,112 @@
+import type { Message } from '../../types/message.js'
+import {
+  resolveAdapter,
+  type AdapterManifestEntry,
+} from '../../services/api/adapterManifest.js'
+import { isNonSyntheticUserMessageText } from './citizenUserText.js'
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function messageRecord(message: unknown): Record<string, unknown> | undefined {
+  return asRecord(asRecord(message)?.message)
+}
+
+function messageRole(message: unknown): string | undefined {
+  const outer = asRecord(message)
+  const inner = messageRecord(message)
+  if (typeof inner?.role === 'string') return inner.role
+  if (typeof outer?.role === 'string') return outer.role
+  return typeof outer?.type === 'string' ? outer.type : undefined
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map(block => {
+      const record = asRecord(block)
+      return typeof record?.text === 'string' ? record.text : ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+function latestUserText(messages: readonly unknown[]): string {
+  for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
+    const message = messages[idx]
+    if (messageRole(message) !== 'user') continue
+    const text = textFromContent(messageRecord(message)?.content ?? asRecord(message)?.content)
+    if (isNonSyntheticUserMessageText(message, text)) return text
+  }
+  return ''
+}
+
+function adapterRequiresQuery(entry: AdapterManifestEntry | undefined): boolean {
+  if (!entry || entry.primitive !== 'locate') return false
+  const schema = asRecord(entry.input_schema_json)
+  const required = schema?.required
+  if (!Array.isArray(required) || !required.includes('query')) return false
+  const properties = asRecord(schema?.properties)
+  return asRecord(properties?.query) !== undefined
+}
+
+function hasUsableQuery(params: Record<string, unknown>): boolean {
+  return typeof params.query === 'string' && params.query.trim().length > 0
+}
+
+function cleanLocationCandidate(candidate: string): string | undefined {
+  const cleaned = candidate
+    .replace(/["'“”‘’]/g, '')
+    .replace(/^(?:오늘|내일|모레|지금|현재|퇴근하고|방금|아까)\s+/u, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/[은는이가을를의]$/u, '')
+    .trim()
+
+  if (cleaned.length < 2 || cleaned.length > 30) return undefined
+  if (/^(?:사람|누구|어디|무엇|오늘|내일|지금)$/u.test(cleaned)) {
+    return undefined
+  }
+  return cleaned
+}
+
+export function deriveLocationQueryFromUserText(text: string): string | undefined {
+  const locativeMatch = text.match(
+    /(?:^|[\s,.;!?])([가-힣A-Za-z0-9][가-힣A-Za-z0-9().·'/-]*(?:\s+[가-힣A-Za-z0-9][가-힣A-Za-z0-9().·'/-]*){0,3})\s*(?:에서|근처|주변|부근|인근|앞|쪽)(?=[은는이가을를에\s,.;!?]|$)/u,
+  )
+  const locativeCandidate = locativeMatch?.[1]
+    ? cleanLocationCandidate(locativeMatch[1])
+    : undefined
+  if (locativeCandidate) return locativeCandidate
+
+  const poiMatch = text.match(
+    /([가-힣A-Za-z0-9][가-힣A-Za-z0-9().·'/-]*(?:역|공항|터미널|해수욕장|시장|공원|병원|학교|대학교|구청|시청|센터))/u,
+  )
+  return poiMatch?.[1] ? cleanLocationCandidate(poiMatch[1]) : undefined
+}
+
+export function repairLocateQueryParamsFromConversation(
+  input: Record<string, unknown>,
+  messages: readonly Message[],
+): Record<string, unknown> {
+  const toolId = typeof input.tool_id === 'string' ? input.tool_id : ''
+  if (!adapterRequiresQuery(resolveAdapter(toolId))) return input
+
+  const params = asRecord(input.params) ?? {}
+  if (hasUsableQuery(params)) return input
+
+  const query = deriveLocationQueryFromUserText(latestUserText(messages))
+  if (!query) return input
+
+  return {
+    ...input,
+    params: {
+      ...params,
+      query,
+    },
+  }
+}

package/tui/src/tools/_shared/nmcAedGuard.ts

@@ -0,0 +1,234 @@
+import type { ToolUseContext, ValidationResult } from '../../Tool.js'
+import { isNonSyntheticUserMessageText } from './citizenUserText.js'
+
+const NMC_EMERGENCY_TOOL_NAME = 'nmc_emergency_search'
+const NMC_AED_TOOL_NAME = 'nmc_aed_site_locate'
+const HIRA_TOOL_NAME_RE = /^hira_/u
+const AED_RE = /(aed|자동심장|심장충격|제세동)/iu
+const ER_RE = /(응급실|응급의료기관|응급의료센터|emergency\s*room|\ber\b)/iu
+const MEDICAL_COLLAPSE_RE =
+  /(사람이\s*쓰러|쓰러졌|쓰러짐|쓰러져|의식[을이가은는\s]*(없|잃|불명)|무의식|심정지|심폐소생|cpr|호흡\s*(없|곤란)|숨\s*(안|못)|collapse|collapsed|unconscious|cardiac\s*arrest|not\s*breathing)/iu
+const NON_MEDICAL_EMERGENCY_RE =
+  /(비상벨|안심벨|emergency\s*(call\s*)?box|call\s*box)/iu
+const NMC_AED_FOLLOWUP_PROMPT =
+  'Required follow-up for this tool chain: the citizen described a collapse, unconsciousness, cardiac-arrest, or AED-relevant medical emergency, and nmc_emergency_search has already returned a successful ER result. Before any final answer, call nmc_aed_site_locate with schema-valid fields using the latest region or location context from this turn. If AED returns no data or an upstream error, report that explicitly with 119 guidance. Do not write final prose until nmc_aed_site_locate has been attempted.'
+const NMC_AED_COMPLETION_PROMPT =
+  'Emergency evidence chain complete: nmc_emergency_search and nmc_aed_site_locate have both been attempted for this collapse/unconsciousness request. Do not emit <tool_call> text, JSON tool-call text, or request another medical search. Write the final Korean emergency guidance now using the actual ER and AED tool results already in this conversation. Put 119 first, then nearest ER, then nearby AED locations or AED upstream/no-data status. Copy AED org, buildAddress, buildPlace, clerkTel, operating-time fields, and distance_km exactly when present; do not rename or summarize building places into new labels. Do not invent distances, walking times, building labels, station-inside labels, operating hours, or phone numbers that are absent from the tool results; omit unavailable details instead.'
+
+type ToolUseRecord = {
+  id: string
+  name: string
+}
+
+export function textFromContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map(block => {
+      if (typeof block === 'string') return block
+      if (typeof block !== 'object' || block === null) return ''
+      const record = block as Record<string, unknown>
+      return typeof record.text === 'string' ? record.text : ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function messageRecord(message: unknown): Record<string, unknown> | undefined {
+  const record = asRecord(message)
+  return asRecord(record?.message)
+}
+
+function messageRole(message: unknown): string | undefined {
+  const record = asRecord(message)
+  const inner = messageRecord(message)
+  if (typeof inner?.role === 'string') return inner.role
+  if (typeof record?.role === 'string') return record.role
+  return typeof record?.type === 'string' ? record.type : undefined
+}
+
+function messageContent(message: unknown): unknown {
+  return messageRecord(message)?.content ?? asRecord(message)?.content
+}
+
+function latestRoleText(context: ToolUseContext, role: 'assistant' | 'user'): string {
+  const messages = Array.isArray(context.messages) ? context.messages : []
+  for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
+    const message = messages[idx]
+    if (messageRole(message) !== role) continue
+    const text = textFromContent(messageContent(message))
+    if (role === 'user' && !isNonSyntheticUserMessageText(message, text)) continue
+    if (text.trim()) return text
+  }
+  return ''
+}
+
+function latestUserTurnStartIndex(messages: readonly unknown[]): number {
+  for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
+    const message = messages[idx]
+    if (messageRole(message) !== 'user') continue
+    const text = textFromContent(messageContent(message))
+    if (isNonSyntheticUserMessageText(message, text)) return idx
+  }
+  return -1
+}
+
+function latestUserTurnMessages(messages: readonly unknown[]): readonly unknown[] {
+  const startIdx = latestUserTurnStartIndex(messages)
+  return startIdx === -1 ? [] : messages.slice(startIdx)
+}
+
+function latestUserTextFromMessages(messages: readonly unknown[]): string {
+  const startIdx = latestUserTurnStartIndex(messages)
+  if (startIdx === -1) return ''
+  return textFromContent(messageContent(messages[startIdx]))
+}
+
+function isMedicalCollapseQuery(text: string): boolean {
+  if (!text.trim()) return false
+  if (AED_RE.test(text) || MEDICAL_COLLAPSE_RE.test(text)) return true
+  return false
+}
+
+function isOnlyNonMedicalEmergencyQuery(text: string): boolean {
+  return NON_MEDICAL_EMERGENCY_RE.test(text) && !isMedicalCollapseQuery(text)
+}
+
+function toolUsesFromMessages(messages: readonly unknown[]): ToolUseRecord[] {
+  const toolUses: ToolUseRecord[] = []
+  for (const message of messages) {
+    const content = messageContent(message)
+    if (!Array.isArray(content)) continue
+    for (const block of content) {
+      const record = asRecord(block)
+      if (record?.type !== 'tool_use') continue
+      if (typeof record.id !== 'string' || typeof record.name !== 'string') continue
+      const input = asRecord(record.input)
+      const nestedToolName =
+        typeof input?.tool_id === 'string' ? input.tool_id : undefined
+      toolUses.push({ id: record.id, name: nestedToolName ?? record.name })
+    }
+  }
+  return toolUses
+}
+
+function parseJsonObject(value: string): Record<string, unknown> | undefined {
+  try {
+    return asRecord(JSON.parse(value))
+  } catch {
+    return undefined
+  }
+}
+
+function isSuccessfulToolResult(block: Record<string, unknown>): boolean {
+  if (block.is_error === true) return false
+  if (typeof block.content !== 'string') return true
+
+  const parsed = parseJsonObject(block.content)
+  if (!parsed) return true
+  if (parsed.ok === false) return false
+  if (parsed.error || parsed.error_code || parsed.errorCode) return false
+
+  const result = asRecord(parsed.result)
+  if (result?.kind === 'error') return false
+  return true
+}
+
+function hasSuccessfulToolResultFor(
+  messages: readonly unknown[],
+  toolName: string,
+): boolean {
+  const idToName = new Map(
+    toolUsesFromMessages(messages).map(toolUse => [toolUse.id, toolUse.name]),
+  )
+  for (const message of messages) {
+    const content = messageContent(message)
+    if (!Array.isArray(content)) continue
+    for (const block of content) {
+      const record = asRecord(block)
+      if (record?.type !== 'tool_result') continue
+      if (typeof record.tool_use_id !== 'string') continue
+      if (idToName.get(record.tool_use_id) !== toolName) continue
+      if (isSuccessfulToolResult(record)) return true
+    }
+  }
+  return false
+}
+
+function hasToolUse(messages: readonly unknown[], toolName: string): boolean {
+  return toolUsesFromMessages(messages).some(toolUse => toolUse.name === toolName)
+}
+
+export function buildNmcAedFollowupPromptIfNeeded({
+  messages,
+  availableToolNames,
+}: {
+  messages: readonly unknown[]
+  availableToolNames: Iterable<string>
+}): string | undefined {
+  const available = new Set(availableToolNames)
+  if (!available.has(NMC_AED_TOOL_NAME)) return undefined
+
+  const userText = latestUserTextFromMessages(messages)
+  const turnMessages = latestUserTurnMessages(messages)
+  if (isOnlyNonMedicalEmergencyQuery(userText)) return undefined
+  if (!isMedicalCollapseQuery(userText)) return undefined
+  if (hasToolUse(turnMessages, NMC_AED_TOOL_NAME)) return undefined
+  if (!hasSuccessfulToolResultFor(turnMessages, NMC_EMERGENCY_TOOL_NAME)) {
+    return undefined
+  }
+  return NMC_AED_FOLLOWUP_PROMPT
+}
+
+export function buildNmcAedCompletionPromptIfNeeded({
+  messages,
+}: {
+  messages: readonly unknown[]
+}): string | undefined {
+  const userText = latestUserTextFromMessages(messages)
+  const turnMessages = latestUserTurnMessages(messages)
+  if (isOnlyNonMedicalEmergencyQuery(userText)) return undefined
+  if (!isMedicalCollapseQuery(userText)) return undefined
+  if (!hasToolUse(turnMessages, NMC_AED_TOOL_NAME)) return undefined
+  if (!hasToolUse(turnMessages, NMC_EMERGENCY_TOOL_NAME)) return undefined
+  return NMC_AED_COMPLETION_PROMPT
+}
+
+export function validateNmcAedToolChoice(
+  toolId: string,
+  context: ToolUseContext,
+): ValidationResult | undefined {
+  if (HIRA_TOOL_NAME_RE.test(toolId)) {
+    const userText = latestRoleText(context, 'user')
+    if (!isOnlyNonMedicalEmergencyQuery(userText) && isMedicalCollapseQuery(userText)) {
+      return {
+        result: false,
+        message:
+          'NMC emergency tool-choice mismatch: a collapse, unconsciousness, cardiac-arrest, or AED-relevant emergency must use official emergency-care evidence, not the general HIRA hospital/clinic search. ' +
+          `Call ${NMC_EMERGENCY_TOOL_NAME} for nearest emergency-room/ER institution data and then ${NMC_AED_TOOL_NAME} for AED locations. ` +
+          'If either NMC adapter returns no data or an upstream error, report that directly with 119 guidance.',
+        errorCode: 1,
+      }
+    }
+  }
+  if (toolId !== NMC_EMERGENCY_TOOL_NAME) return undefined
+  const assistantText = latestRoleText(context, 'assistant')
+  const userText = latestRoleText(context, 'user')
+  const assistantIsAskingForAed = AED_RE.test(assistantText) && !ER_RE.test(assistantText)
+  const userAskedOnlyForAed = AED_RE.test(userText) && !ER_RE.test(userText)
+  if (!assistantIsAskingForAed && !userAskedOnlyForAed) return undefined
+  return {
+    result: false,
+    message:
+      'NMC tool-choice mismatch: nmc_emergency_search answers emergency-room/ER institution data, not AED locations. ' +
+      `Call ${NMC_AED_TOOL_NAME} for AED/자동심장충격기/자동제세동기 requests. ` +
+      'If the AED API returns no data or an upstream error, report that result directly instead of substituting ER data.',
+    errorCode: 1,
+  }
+}

package/tui/src/tools/_shared/protectedCheckGuard.ts

@@ -0,0 +1,207 @@
+import type { ToolUseContext, ValidationResult } from '../../Tool.js'
+import {
+  listAdapters,
+  resolveAdapter,
+} from '../../services/api/adapterManifest.js'
+import { isNonSyntheticUserMessageText } from './citizenUserText.js'
+import { textFromContent } from './nmcAedGuard.js'
+
+const PROTECTED_QUERY_RE =
+  /(본인확인|인증|간편인증|모바일\s*(?:신분증|id)|mobile\s*id|마이데이터|mydata|증명원|소득금액증명|소득금액증명원|주민등록등본|민원|발급)/iu
+const VERIFY_ALIAS_RE =
+  /^(?:check|mobile_id|modid|simple_auth_module|ganpyeon_injeung|gongdong_injeungseo|geumyung_injeungseo|mydata|any_id_sso)$/iu
+const PROTECTED_CHECK_TOOL_NAMES = new Set([
+  'mock_verify_module_simple_auth',
+  'mock_verify_ganpyeon_injeung',
+  'mock_verify_mobile_id',
+  'mock_verify_mydata',
+  'mock_verify_digital_onepass',
+  'mock_verify_gongdong_injeungseo',
+  'mock_verify_geumyung_injeungseo',
+  'mock_verify_module_modid',
+  'mock_verify_module_kec',
+  'mock_verify_module_geumyung',
+  'mock_verify_module_any_id_sso',
+])
+const PROTECTED_CHECK_COMPLETION_PROMPT =
+  'Protected-domain evidence chain complete: a registered check adapter has already been attempted for this certificate, authentication, identity, or protected-service request. Do not emit <tool_call> text, JSON tool-call text, or request another identity tool. Write the final Korean answer now using the actual check result already in this conversation. If the result is permission_denied, unavailable, or mock-only, state that UMMAYA cannot complete the protected action in-session, then give official handoff options without claiming issuance succeeded.'
+const PROTECTED_CHECK_REPAIR_PROMPT =
+  'Protected-domain final-answer repair: the previous assistant message was invalid because it printed JSON tool-call text after a registered check adapter result. Do not call or print any tool. Write one Korean prose answer only. Use the existing check result already in this conversation. If the result is permission_denied, unavailable, or mock-only, state that UMMAYA cannot complete the protected action in-session, then give official handoff options such as Government24, Hometax, mobile ID, or 간편인증 without claiming issuance succeeded.'
+const PROTECTED_TOOL_CALL_TEXT_RE =
+  /<tool_call>|"name"\s*:\s*"[^"]*(?:check|verify|auth|mobile|simple|ganpyeon|mydata)[^"]*"|"arguments"\s*:\s*\{/iu
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function messageRecord(message: unknown): Record<string, unknown> | undefined {
+  return asRecord(asRecord(message)?.message)
+}
+
+function messageRole(message: unknown): string | undefined {
+  const record = asRecord(message)
+  const inner = messageRecord(message)
+  if (typeof inner?.role === 'string') return inner.role
+  if (typeof record?.role === 'string') return record.role
+  return typeof record?.type === 'string' ? record.type : undefined
+}
+
+function messageContent(message: unknown): unknown {
+  return messageRecord(message)?.content ?? asRecord(message)?.content
+}
+
+function latestUserText(context: ToolUseContext): string {
+  const messages = Array.isArray(context.messages) ? context.messages : []
+  for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
+    const message = messages[idx]
+    if (messageRole(message) !== 'user') continue
+    const text = textFromContent(messageContent(message))
+    if (isNonSyntheticUserMessageText(message, text)) return text
+  }
+  return ''
+}
+
+function userTextFromMessages(messages: readonly unknown[]): string {
+  return messages
+    .filter(message => messageRole(message) === 'user')
+    .map(message => ({ message, text: textFromContent(messageContent(message)) }))
+    .filter(({ message, text }) => isNonSyntheticUserMessageText(message, text))
+    .map(({ text }) => text)
+    .join('\n')
+}
+
+function hasProtectedCheckToolUse(messages: readonly unknown[]): boolean {
+  for (const message of messages) {
+    const content = messageContent(message)
+    if (!Array.isArray(content)) continue
+    for (const block of content) {
+      const record = asRecord(block)
+      if (record?.type !== 'tool_use') continue
+      if (
+        typeof record.name === 'string' &&
+        PROTECTED_CHECK_TOOL_NAMES.has(record.name)
+      ) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+function latestAssistantText(messages: readonly unknown[]): string {
+  for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
+    const message = messages[idx]
+    if (messageRole(message) !== 'assistant') continue
+    const text = textFromContent(messageContent(message))
+    if (text.trim()) return text
+  }
+  return ''
+}
+
+function hasRepairPrompt(messages: readonly unknown[]): boolean {
+  return messages.some(message =>
+    textFromContent(messageContent(message)).includes(
+      'Protected-domain final-answer repair',
+    ),
+  )
+}
+
+function checkAdapterIds(): string[] {
+  return listAdapters()
+    .filter(entry => entry.primitive === 'check')
+    .map(entry => entry.tool_id)
+}
+
+function selectSuggestions(toolId: string, userText: string): string[] {
+  const available = checkAdapterIds()
+  const wantsMobile = /mobile\s*id|모바일\s*(?:신분증|id)|mobile_id/iu.test(
+    `${toolId} ${userText}`,
+  )
+  const wantsSimple =
+    /simple_auth|간편인증|ganpyeon|소득금액증명|증명원|민원|발급/iu.test(
+      `${toolId} ${userText}`,
+    )
+  const wantsMydata = /mydata|마이데이터/iu.test(`${toolId} ${userText}`)
+  const preferred = [
+    wantsMobile ? 'mock_verify_mobile_id' : undefined,
+    wantsSimple ? 'mock_verify_module_simple_auth' : undefined,
+    wantsSimple ? 'mock_verify_ganpyeon_injeung' : undefined,
+    wantsMydata ? 'mock_verify_mydata' : undefined,
+  ].filter((id): id is string => typeof id === 'string' && available.includes(id))
+  const merged = [...preferred, ...available]
+  return [...new Set(merged)].slice(0, 3)
+}
+
+export function validateProtectedCheckToolChoice(
+  toolId: string,
+  context: ToolUseContext,
+): ValidationResult | undefined {
+  const userText = latestUserText(context)
+  const adapter = resolveAdapter(toolId)
+  if (adapter?.primitive === 'check') {
+    return {
+      result: false,
+      message:
+        `Protected-domain tool-choice mismatch: ${toolId} is a check adapter but was called through find. ` +
+        `Call check({tool_id:${JSON.stringify(toolId)}, params:{...}}) instead. ` +
+        'Do not call check adapters through find.',
+      errorCode: 1,
+    }
+  }
+  if (!PROTECTED_QUERY_RE.test(userText) && !VERIFY_ALIAS_RE.test(toolId)) {
+    return undefined
+  }
+  if (!VERIFY_ALIAS_RE.test(toolId)) return undefined
+  const suggestions = selectSuggestions(toolId, userText)
+  if (suggestions.length === 0) return undefined
+  return {
+    result: false,
+    message:
+      `Protected-domain tool-choice mismatch: ${toolId} is not a registered find adapter. ` +
+      `Use the check primitive with a registered check adapter such as ${suggestions.join(', ')}. ` +
+      'Do not call identity, authentication, consent, or certificate adapters through find.',
+    errorCode: 1,
+  }
+}
+
+export function buildProtectedCheckCompletionPromptIfNeeded({
+  messages,
+}: {
+  messages: readonly unknown[]
+}): string | undefined {
+  const userText = userTextFromMessages(messages)
+  if (!PROTECTED_QUERY_RE.test(userText)) return undefined
+  if (!hasProtectedCheckToolUse(messages)) return undefined
+  return PROTECTED_CHECK_COMPLETION_PROMPT
+}
+
+export function buildProtectedCheckFinalAnswerRepairPromptIfNeeded({
+  messages,
+}: {
+  messages: readonly unknown[]
+}): string | undefined {
+  const userText = userTextFromMessages(messages)
+  if (!PROTECTED_QUERY_RE.test(userText)) return undefined
+  if (!hasProtectedCheckToolUse(messages)) return undefined
+  if (hasRepairPrompt(messages)) return undefined
+  const assistantText = latestAssistantText(messages)
+  if (!PROTECTED_TOOL_CALL_TEXT_RE.test(assistantText)) return undefined
+  return PROTECTED_CHECK_REPAIR_PROMPT
+}
+
+export function shouldWithholdProtectedCheckToolCallText({
+  messages,
+  candidate,
+}: {
+  messages: readonly unknown[]
+  candidate: unknown
+}): boolean {
+  if (hasRepairPrompt(messages)) return false
+  return (
+    buildProtectedCheckFinalAnswerRepairPromptIfNeeded({
+      messages: [...messages, candidate],
+    }) !== undefined
+  )
+}

package/tui/src/tools/_shared/rootPrimitiveInput.ts

@@ -0,0 +1,67 @@
+export const ROOT_PRIMITIVE_TOOL_IDS = new Set([
+  'find',
+  'locate',
+  'check',
+  'send',
+])
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+export function isRootPrimitiveToolId(value: unknown): value is string {
+  return typeof value === 'string' && ROOT_PRIMITIVE_TOOL_IDS.has(value)
+}
+
+export function normalizeRootPrimitiveAdapterEnvelope(
+  expectedPrimitive: string,
+  value: unknown,
+): unknown {
+  const record = asRecord(value)
+  if (!record) return value
+  const topLevelToolId = record.tool_id
+
+  const params = asRecord(record.params)
+  if (!params) return value
+  const nestedToolId = params.tool_id
+  if (
+    typeof topLevelToolId === 'string' &&
+    topLevelToolId.length > 0 &&
+    topLevelToolId !== expectedPrimitive &&
+    nestedToolId === topLevelToolId
+  ) {
+    const { tool_id: _nestedToolId, ...adapterParams } = params
+    return {
+      ...record,
+      params: adapterParams,
+    }
+  }
+
+  if (topLevelToolId !== expectedPrimitive) return value
+  if (
+    typeof nestedToolId !== 'string' ||
+    nestedToolId.trim().length === 0 ||
+    ROOT_PRIMITIVE_TOOL_IDS.has(nestedToolId)
+  ) {
+    return value
+  }
+
+  const { tool_id: _nestedToolId, ...adapterParams } = params
+  return {
+    ...record,
+    tool_id: nestedToolId,
+    params: adapterParams,
+  }
+}
+
+export function rootPrimitiveSelfTargetMessage(
+  toolId: string,
+  primitiveLabel: string,
+): string {
+  return (
+    `Root primitive '${toolId}' is not a ${primitiveLabel} adapter tool_id. ` +
+    'Pick a concrete adapter from <available_adapters>.'
+  )
+}