ummaya 0.2.3 → 0.2.5

package/tui/src/tools/BashTool/shellPermissionGauntlet.ts

@@ -0,0 +1,97 @@
+import type { ToolPermissionContext } from '../../Tool.js'
+import type { PermissionResult } from '../../utils/permissions/PermissionResult.js'
+
+type ShellRiskClass = {
+  readonly kind: 'destructive' | 'protected-ax'
+  readonly reason: string
+}
+
+type DestructiveWarningFn = (command: string) => string | null
+
+const PROTECTED_AX_PATTERNS: readonly { readonly pattern: RegExp; readonly reason: string }[] = [
+  {
+    pattern:
+      /\b(?:curl|wget|http|https|invoke-webrequest|invoke-restmethod|iwr|irm)\b[\s\S]*(?:data\.go\.kr|www\.gov\.kr|gov\.kr|hometax\.go\.kr|wetax\.go\.kr|openbanking|kftc|mobileid|omnidid|omni[-_ ]?one)/iu,
+    reason:
+      'Shell command appears to call Korean public-service, identity, payment, or government infrastructure',
+  },
+  {
+    pattern:
+      /\b(?:hometax|government24|gov24|wetax|openbanking|kftc|mobile[-_ ]?id|certificate|public[-_ ]?certificate|identity|payment|pipa|정부24|홈택스|위택스|모바일신분증|공동인증서|금융인증서)\b/iu,
+    reason:
+      'Shell command references protected national AX, identity, certificate, or payment surfaces',
+  },
+  {
+    pattern:
+      /\bUMMAYA_[A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|CERT|CERTIFICATE|API_KEY|AUTH_KEY|SERVICE_KEY)\b/u,
+    reason:
+      'Shell command references UMMAYA credential material for protected infrastructure access',
+  },
+]
+
+function shouldTreatModeAsBypass(toolPermissionContext: ToolPermissionContext): boolean {
+  return (
+    toolPermissionContext.mode === 'bypassPermissions' ||
+    (toolPermissionContext.mode === 'plan' &&
+      toolPermissionContext.isBypassPermissionsModeAvailable)
+  )
+}
+
+export function classifyShellRiskForPermissionGauntlet(
+  command: string,
+  getDestructiveWarning: DestructiveWarningFn,
+): ShellRiskClass | null {
+  const destructiveWarning = getDestructiveWarning(command)
+  if (destructiveWarning !== null) {
+    return {
+      kind: 'destructive',
+      reason: destructiveWarning,
+    }
+  }
+
+  for (const { pattern, reason } of PROTECTED_AX_PATTERNS) {
+    if (pattern.test(command)) {
+      return {
+        kind: 'protected-ax',
+        reason,
+      }
+    }
+  }
+
+  return null
+}
+
+export function getBypassImmuneShellPermissionResult(
+  command: string,
+  toolName: string,
+  toolPermissionContext: ToolPermissionContext,
+  getDestructiveWarning: DestructiveWarningFn,
+): PermissionResult | null {
+  if (!shouldTreatModeAsBypass(toolPermissionContext)) {
+    return null
+  }
+
+  const risk = classifyShellRiskForPermissionGauntlet(
+    command,
+    getDestructiveWarning,
+  )
+  if (risk === null) {
+    return null
+  }
+
+  const reason =
+    risk.kind === 'destructive'
+      ? `Destructive shell command requires explicit approval even in bypassPermissions mode: ${risk.reason}`
+      : `Protected AX-adjacent shell command requires explicit approval even in bypassPermissions mode: ${risk.reason}`
+
+  return {
+    behavior: 'ask',
+    message: `${toolName} command requires explicit approval. ${reason}`,
+    decisionReason: {
+      type: 'safetyCheck',
+      reason,
+      classifierApprovable: false,
+    },
+    suggestions: [],
+  }
+}

package/tui/src/tools/BashTool/uiLoader.ts

@@ -0,0 +1,37 @@
+import { createRequire } from 'node:module'
+
+type BashUIRuntime = Pick<
+  typeof import('./UI.js'),
+  | 'BackgroundHint'
+  | 'renderToolResultMessage'
+  | 'renderToolUseErrorMessage'
+  | 'renderToolUseMessage'
+  | 'renderToolUseProgressMessage'
+  | 'renderToolUseQueuedMessage'
+>
+
+const requireModule = createRequire(import.meta.url)
+let cachedBashUI: BashUIRuntime | undefined
+
+function isBashUIRuntime(value: unknown): value is BashUIRuntime {
+  if (typeof value !== 'object' || value === null) return false
+  const module = value as Partial<Record<keyof BashUIRuntime, unknown>>
+  return (
+    typeof module.BackgroundHint === 'function' &&
+    typeof module.renderToolResultMessage === 'function' &&
+    typeof module.renderToolUseErrorMessage === 'function' &&
+    typeof module.renderToolUseMessage === 'function' &&
+    typeof module.renderToolUseProgressMessage === 'function' &&
+    typeof module.renderToolUseQueuedMessage === 'function'
+  )
+}
+
+export function loadBashUI(): BashUIRuntime {
+  if (cachedBashUI !== undefined) return cachedBashUI
+  const loaded: unknown = requireModule('./UI.js')
+  if (!isBashUIRuntime(loaded)) {
+    throw new Error('Bash UI module did not expose the expected renderers')
+  }
+  cachedBashUI = loaded
+  return loaded
+}

package/tui/src/tools/BriefTool/upload.ts

@@ -7,7 +7,7 @@
  * returned file_uuid alongside the path. Web resolves file_uuid → preview;
  * desktop/local try path first.
  *
- * Best-effort: any failure (no token, bridge off, network error, 4xx) logs
+ * Best-effort: each failure (no token, bridge off, network error, 4xx) logs
  * debug and returns undefined. The attachment still carries {path, size,
  * isImage}, so local-terminal and same-machine-desktop render unaffected.
  */

package/tui/src/tools/CalculatorTool/parser.ts

@@ -2,11 +2,11 @@
  * Restricted-grammar expression parser + evaluator using the shunting-yard algorithm.
  *
  * Allowed characters: 0-9  .  +  -  *  /  %  (  )  whitespace
- * Disallowed: any letter, underscore, $, !,  ^, &, |, ~, <, >, =, etc.
+ * Disallowed: letters, underscore, $, !,  ^, &, |, ~, <, >, =, etc.
  *
  * Numeric representation strategy:
  *   - Parse every numeric literal as a string to avoid IEEE-754 precision loss.
- *   - Track whether any division produces a non-integer result.
+ *   - Track whether division produces a non-integer result.
  *   - Arithmetic is carried out with BigInt when all operands are integers
  *     (denominator check for /); otherwise falls back to JS number with
  *     toFixed(precision) rounding, which is sufficient for the "up to 28 digits"

package/tui/src/tools/DocumentPrimitive/DocumentPrimitive.ts

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: Apache-2.0
+// UMMAYA-original — DocumentPrimitive.
+
+import React from 'react'
+import { z } from 'zod/v4'
+import { Text } from '../../ink.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { getOrCreateUmmayaBridge } from '../../ipc/bridgeSingleton.js'
+import { getOrCreatePendingCallRegistry } from '../../ipc/pendingCallSingleton.js'
+import { dispatchPrimitive } from '../_shared/dispatchPrimitive.js'
+import {
+  applyDocumentVisualRenderGateToOutput,
+  isDocumentVisualRenderFailedOutput,
+  renderDocumentToolResultIfPresent,
+} from '../_shared/documentToolResultRender.js'
+import {
+  renderVerboseInputJson,
+  renderVerboseOutputJson,
+} from '../_shared/verboseRender.js'
+import {
+  isPrimitiveResultPreviewTruncated,
+  renderCompactPrimitiveResult,
+} from '../_shared/compactPrimitiveResult.js'
+import { resolveDocumentPrimitiveTimeoutMs } from '../_shared/documentPrimitiveTimeout.js'
+import {
+  DOCUMENT_TOOL_NAME,
+  DESCRIPTION,
+  DOCUMENT_TOOL_PROMPT,
+} from './prompt.js'
+import {
+  latestUserTextFromContext,
+  normalizeDocumentPrimitiveInputForDispatch as normalizeDispatchInput,
+  operationOf,
+} from './dispatchNormalization.js'
+import { modelVisibleDocumentOutput } from './modelVisibleOutput.js'
+
+export { normalizeDocumentPrimitiveInputForDispatch } from './dispatchNormalization.js'
+
+const documentRefSchema = z
+  .object({
+    path: z.string().min(1).optional(),
+    artifact_id: z.string().min(1).optional(),
+    expected_format: z
+      .enum(['hwpx', 'hwp', 'docx', 'pdf', 'xlsx', 'pptx'])
+      .optional(),
+  })
+  .passthrough()
+
+const inputSchema = lazySchema(() =>
+  z
+    .object({
+      correlation_id: z.string().min(1),
+      document: documentRefSchema,
+      operation: z
+        .enum(['inspect', 'extract', 'fill', 'style', 'validate', 'save'])
+        .optional(),
+      instruction: z.string().min(1),
+      destination_path: z.string().min(1).optional(),
+      destination_display_name: z.string().min(1).optional(),
+      template_id: z.string().min(1).optional(),
+      patches: z.array(z.unknown()).optional(),
+      styles: z.array(z.unknown()).optional(),
+    })
+    .passthrough(),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+export type Input = z.infer<InputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.discriminatedUnion('ok', [
+    z.object({
+      ok: z.literal(true),
+      result: z.unknown(),
+      outbound_traces: z.array(z.unknown()).optional(),
+    }),
+    z.object({
+      ok: z.literal(false),
+      error: z.object({
+        kind: z.string(),
+        message: z.string(),
+      }),
+      result: z.unknown().optional(),
+      outbound_traces: z.array(z.unknown()).optional(),
+    }),
+  ]),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type Output = z.infer<OutputSchema>
+
+function documentTarget(input: Input): string {
+  const document = input.document as Record<string, unknown>
+  const path = typeof document.path === 'string' ? document.path : undefined
+  const artifactId =
+    typeof document.artifact_id === 'string' ? document.artifact_id : undefined
+  return path ?? artifactId ?? 'document'
+}
+
+function documentAction(input: Input): string {
+  switch (operationOf(input)) {
+    case 'inspect':
+      return 'Inspect document'
+    case 'extract':
+      return 'Read document'
+    case 'style':
+      return 'Apply document formatting'
+    case 'validate':
+      return 'Validate public-form rules'
+    case 'save':
+      return 'Save document'
+    case 'fill':
+    default:
+      return 'Write document'
+  }
+}
+
+function buildDocumentErrorRows(output: Extract<Output, { ok: false }>): React.ReactNode[] {
+  return [
+    React.createElement(
+      Text,
+      { key: 'document-error', color: 'red' },
+      `Document failed: ${output.error.message}`,
+    ),
+  ]
+}
+
+export const DocumentPrimitive = buildTool({
+  name: DOCUMENT_TOOL_NAME,
+
+  searchHint:
+    'document hwpx hwp docx pdf xlsx pptx form fill render save diff public document',
+
+  maxResultSizeChars: 100_000,
+
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+
+  isEnabled() {
+    return true
+  },
+
+  isConcurrencySafe() {
+    return false
+  },
+
+  isReadOnly(input?: Input) {
+    const operation = input ? operationOf(input) : 'fill'
+    return operation === 'inspect' || operation === 'extract' || operation === 'validate'
+  },
+
+  isDestructive() {
+    return false
+  },
+
+  async description() {
+    return DESCRIPTION
+  },
+
+  async prompt() {
+    return DOCUMENT_TOOL_PROMPT
+  },
+
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    const gatedOutput = applyDocumentVisualRenderGateToOutput(output)
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: JSON.stringify(modelVisibleDocumentOutput(gatedOutput)),
+      ...(isDocumentVisualRenderFailedOutput(gatedOutput) ? { is_error: true } : {}),
+    }
+  },
+
+  renderToolUseMessage(input: Input, options: { verbose: boolean }) {
+    if (options.verbose) return renderVerboseInputJson(input)
+    return `${documentAction(input)}: ${documentTarget(input)}`
+  },
+
+  isMcp: false,
+
+  async validateInput(input: Input, _context: ToolUseContext) {
+    if (typeof input !== 'object' || input === null) {
+      return {
+        result: false as const,
+        message: 'document expects a JSON object argument.',
+        errorCode: 1,
+      }
+    }
+    const document = input.document as Record<string, unknown> | undefined
+    if (!document || typeof document !== 'object') {
+      return {
+        result: false as const,
+        message: 'document.document is required.',
+        errorCode: 1,
+      }
+    }
+    if (
+      typeof document.path !== 'string' &&
+      typeof document.artifact_id !== 'string'
+    ) {
+      return {
+        result: false as const,
+        message: 'document requires either document.path or document.artifact_id.',
+        errorCode: 1,
+      }
+    }
+    if (typeof input.instruction !== 'string' || input.instruction.trim() === '') {
+      return {
+        result: false as const,
+        message: 'document.instruction is required.',
+        errorCode: 1,
+      }
+    }
+    return { result: true as const }
+  },
+
+  renderToolResultMessage(
+    output: Output,
+    _progress: unknown,
+    options: { verbose: boolean; isTranscriptMode?: boolean } = { verbose: false },
+  ) {
+    const gatedOutput = applyDocumentVisualRenderGateToOutput(output) as Output
+    const documentResult = renderDocumentToolResultIfPresent(gatedOutput, options)
+    if (documentResult !== null) return documentResult
+    if (options.verbose || options.isTranscriptMode) {
+      return renderVerboseOutputJson(gatedOutput)
+    }
+    return renderCompactPrimitiveResult(
+      gatedOutput.ok
+        ? [React.createElement(Text, { key: 'document-ok' }, 'Document result received.')]
+        : buildDocumentErrorRows(gatedOutput),
+    )
+  },
+
+  isResultTruncated(output: Output): boolean {
+    if (output.ok) return false
+    return isPrimitiveResultPreviewTruncated(buildDocumentErrorRows(output))
+  },
+
+  async call(input, context) {
+    const args = normalizeDispatchInput(
+      input as Input,
+      latestUserTextFromContext(context),
+    )
+    const result = await dispatchPrimitive<Output>({
+      primitive: 'document',
+      args,
+      context,
+      registry: getOrCreatePendingCallRegistry(),
+      bridge: getOrCreateUmmayaBridge(),
+      timeoutMs: resolveDocumentPrimitiveTimeoutMs(),
+    })
+    return {
+      ...result,
+      data: applyDocumentVisualRenderGateToOutput(result.data) as Output,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

package/tui/src/tools/DocumentPrimitive/dispatchNormalization.ts

@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToolUseContext } from '../../Tool.js'
+import { lastLocalDocumentPath } from './documentDestinationPath.js'
+import { normalizeDocumentMutationPayloadsForDispatch } from './documentPatchNormalization.js'
+
+const WRITE_INTENT_RE =
+  /(작성|수정|편집|채우|채워|입력|변경|저장|보정|서식|글꼴|글자색|배경색|정렬|굵게|write|edit|fill|apply|save|style|format|bold)/iu
+const READ_ONLY_INTENT_RE =
+  /(읽기\s*전용|수정\s*없이|변경\s*없이|저장\s*없이|열람만|확인만|추출|파악|쓰지\s*마|작성하지\s*마|반영하지\s*마|저장하지\s*마|inspect|extract|read\s*only)/iu
+const DEFERRED_WRITE_INTENT_RE =
+  /((아직|먼저|초안).{0,40}(쓰지\s*마|작성하지\s*마|저장하지\s*마|반영하지\s*마))|((쓰지\s*마|작성하지\s*마|저장하지\s*마|반영하지\s*마).{0,40}(아직|먼저|초안))/iu
+const APPROVED_DERIVATIVE_SAVE_RE =
+  /((승인|approved).{0,100}(저장|복사본|derivative|\/[^\s]+))|((저장|복사본|derivative|\/[^\s]+).{0,100}(승인|approved))/iu
+const QUESTION_FIRST_AUTHORING_RE =
+  /(근거|질문|먼저\s*물|먼저\s*질문|초안|승인|evidence|question|draft|approval)/iu
+const STRUCTURE_INSPECTION_RE =
+  /(구조|빈칸|문항|양식|필드|항목).*(확인|파악|검토)|(?:확인|파악|검토).*(구조|빈칸|문항|양식|필드|항목)/iu
+const INTERNAL_DISPATCH_KEYS = new Set(['__ummaya_display_operation'])
+const READ_ONLY_OPERATIONS = new Set(['inspect', 'extract', 'validate'])
+const READ_ONLY_MUTATION_KEYS = new Set([
+  'destination_path',
+  'destination_display_name',
+  'patches',
+  'styles',
+  'approved_draft_id',
+  'approved_draft_sha256',
+])
+
+export type DocumentPrimitiveDispatchInput = {
+  readonly document?: unknown
+  readonly operation?: string
+  readonly instruction?: string
+  readonly destination_path?: string
+  readonly patches?: readonly unknown[]
+  readonly styles?: readonly unknown[]
+  readonly [key: string]: unknown
+}
+
+export function normalizeDocumentPrimitiveInputForDispatch(
+  input: DocumentPrimitiveDispatchInput,
+  userText: string | undefined,
+): Record<string, unknown> {
+  const operation = operationOf(input, userText)
+  const text = `${input.instruction ?? ''}\n${userText ?? ''}`
+  const destinationPath =
+    typeof input.destination_path === 'string' ||
+    READ_ONLY_OPERATIONS.has(operation) ||
+    !hasApprovedDerivativeSaveIntent(input, text)
+      ? undefined
+      : lastLocalDocumentPath(text)
+  const args = normalizeDocumentLocatorForDispatch(
+    normalizeDocumentMutationPayloadsForDispatch(
+      stripDispatchOnlyFields({
+        ...input,
+        operation,
+        ...(destinationPath === undefined ? {} : { destination_path: destinationPath }),
+      }),
+      userText,
+    ),
+  )
+  if (userText === undefined || hasPatchOrStylePayload(input)) {
+    return args
+  }
+
+  const instruction = typeof input.instruction === 'string'
+    ? input.instruction.trim()
+    : ''
+  if (instruction.includes(userText)) {
+    return args
+  }
+  return {
+    ...args,
+    instruction: instruction
+      ? `${instruction}\n\nOriginal user request:\n${userText}`
+      : userText,
+  }
+}
+
+export function operationOf(
+  input: DocumentPrimitiveDispatchInput,
+  userText?: string,
+): string {
+  const operation = typeof input.operation === 'string' ? input.operation : 'fill'
+  if (hasReadOnlyIntentFromText(input, userText)) {
+    return operation === 'extract' ? 'extract' : 'inspect'
+  }
+  if (shouldPreserveQuestionFirstRead(input, userText, operation)) {
+    return operation
+  }
+  const displayOperation =
+    typeof input.__ummaya_display_operation === 'string'
+      ? input.__ummaya_display_operation
+      : undefined
+  if (
+    displayOperation === 'fill' ||
+    displayOperation === 'style' ||
+    displayOperation === 'save'
+  ) {
+    return displayOperation
+  }
+  if (
+    (operation === 'inspect' || operation === 'extract') &&
+    hasWriteIntentFromText(input, userText)
+  ) {
+    return 'fill'
+  }
+  return operation
+}
+
+export function latestUserTextFromContext(context: ToolUseContext): string | undefined {
+  const messages = contextRecord(context).messages
+  if (!Array.isArray(messages)) return undefined
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = recordFrom(messages[index])
+    if (message === null) continue
+    const sdkMessage = recordFrom(message.message)
+    if (!isUserMessageRecord(message, sdkMessage)) continue
+    const content = sdkMessage?.content ?? message.content
+    const text = textFromMessageContent(content)
+    if (text !== undefined) return text
+  }
+  return undefined
+}
+
+function normalizeDocumentLocatorForDispatch(
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const document = recordFrom(args.document)
+  if (document === null) {
+    return args
+  }
+  if (
+    nonEmptyString(document.artifact_id) === undefined ||
+    nonEmptyString(document.path) === undefined
+  ) {
+    return args
+  }
+  const normalizedDocument: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(document)) {
+    if (key !== 'path') {
+      normalizedDocument[key] = value
+    }
+  }
+  return {
+    ...args,
+    document: normalizedDocument,
+  }
+}
+
+function stripDispatchOnlyFields(args: Record<string, unknown>): Record<string, unknown> {
+  const operation = typeof args.operation === 'string' ? args.operation : 'fill'
+  const readOnlyOperation = READ_ONLY_OPERATIONS.has(operation)
+  const cleaned: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(args)) {
+    if (INTERNAL_DISPATCH_KEYS.has(key)) continue
+    if (readOnlyOperation && READ_ONLY_MUTATION_KEYS.has(key)) continue
+    cleaned[key] = value
+  }
+  return cleaned
+}
+
+function shouldPreserveQuestionFirstRead(
+  input: DocumentPrimitiveDispatchInput,
+  userText: string | undefined,
+  operation: string,
+): boolean {
+  if (operation !== 'inspect' && operation !== 'extract') {
+    return false
+  }
+  if (hasPatchOrStylePayload(input)) {
+    return false
+  }
+  const text = `${input.instruction ?? ''}\n${userText ?? ''}`
+  if (hasApprovedDerivativeSaveIntent(input, text)) {
+    return false
+  }
+  if (operation === 'inspect' && STRUCTURE_INSPECTION_RE.test(input.instruction ?? '')) {
+    return true
+  }
+  return QUESTION_FIRST_AUTHORING_RE.test(text) && WRITE_INTENT_RE.test(text)
+}
+
+function hasWriteIntentFromText(
+  input: DocumentPrimitiveDispatchInput,
+  userText: string | undefined,
+): boolean {
+  if (typeof input.destination_path === 'string') return true
+  if (hasPatchOrStylePayload(input)) return true
+  if (userText !== undefined) {
+    return !READ_ONLY_INTENT_RE.test(userText) && WRITE_INTENT_RE.test(userText)
+  }
+  if (READ_ONLY_INTENT_RE.test(input.instruction ?? '')) return false
+  return WRITE_INTENT_RE.test(input.instruction ?? '')
+}
+
+function hasReadOnlyIntentFromText(
+  input: DocumentPrimitiveDispatchInput,
+  userText: string | undefined,
+): boolean {
+  const text = userText ?? input.instruction ?? ''
+  if (!READ_ONLY_INTENT_RE.test(text)) {
+    return false
+  }
+  if (hasApprovedDerivativeSaveIntent(input, text)) {
+    return false
+  }
+  return true
+}
+
+function hasPatchOrStylePayload(input: DocumentPrimitiveDispatchInput): boolean {
+  return (Array.isArray(input.patches) && input.patches.length > 0) ||
+    (Array.isArray(input.styles) && input.styles.length > 0)
+}
+
+function hasApprovedDerivativeSaveIntent(
+  input: DocumentPrimitiveDispatchInput,
+  text: string,
+): boolean {
+  if (DEFERRED_WRITE_INTENT_RE.test(text)) {
+    return false
+  }
+  if (APPROVED_DERIVATIVE_SAVE_RE.test(text)) {
+    return true
+  }
+  return typeof input.destination_path === 'string' &&
+    /(승인|approved|검토용\s*복사본|원본은\s*건드리지\s*말)/iu.test(text) &&
+    /(저장|save|\/[^\s]+)/iu.test(text)
+}
+
+function textFromMessageContent(content: unknown): string | undefined {
+  if (typeof content === 'string' && content.trim() !== '') {
+    return content
+  }
+  if (!Array.isArray(content)) {
+    return undefined
+  }
+  const text = content
+    .map(block => {
+      const item = recordFrom(block)
+      return item?.type === 'text' && typeof item.text === 'string'
+        ? item.text
+        : ''
+    })
+    .filter(Boolean)
+    .join('\n')
+    .trim()
+  return text === '' ? undefined : text
+}
+
+function isUserMessageRecord(
+  message: Record<string, unknown>,
+  sdkMessage: Record<string, unknown> | null,
+): boolean {
+  return message.type === 'user' || message.role === 'user' || sdkMessage?.role === 'user'
+}
+
+function contextRecord(context: ToolUseContext): Record<string, unknown> {
+  return context
+}
+
+function recordFrom(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : null
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined
+}