ummaya 0.2.4 → 0.2.5

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

@@ -14,6 +14,7 @@ import type { IPCBridge } from '../../ipc/bridge.js'
 import type { ToolCallFrame, ToolResultFrame } from '../../ipc/frames.generated.js'
 import { getUmmayaBridgeSessionId } from '../../ipc/bridgeSingleton.js'
 import type { ToolUseContext, ToolResult } from '../../Tool.js'
+import { argumentsForPrimitive } from './documentDispatchArguments.js'
 import { PendingCallRegistry } from './pendingCallRegistry.js'
 
 // ---------------------------------------------------------------------------
@@ -49,7 +50,7 @@ function _resolveTimeoutMs(override?: number): number {
 // ---------------------------------------------------------------------------
 
 export interface DispatchPrimitiveOpts {
-  primitive: 'find' | 'locate' | 'check' | 'send'
+  primitive: 'find' | 'locate' | 'check' | 'send' | 'document'
   /** Concrete model-facing tool name. Defaults to the primitive for legacy root calls. */
   toolName?: string
   /** Forwarded verbatim into tool_call frame arguments (FR-009). */
@@ -78,7 +79,7 @@ export function _resetCheckpointState(): void {
 }
 
 function _maybeEmitCheckpoint(
-  primitive: 'find' | 'locate' | 'check' | 'send',
+  primitive: 'find' | 'locate' | 'check' | 'send' | 'document',
   frame: ToolResultFrame,
 ): void {
   if (process.env['UMMAYA_SMOKE_CHECKPOINTS'] !== 'true') return
@@ -146,8 +147,7 @@ export async function dispatchPrimitive<O = unknown>(
   // it does not synthesize the follow-up assistant turn for this Tool.call().
   // ------------------------------------------------------------------
 
-  const toolUseId =
-    (opts.context as Record<string, unknown>)['toolUseId'] as string | undefined
+  const toolUseId = opts.context.toolUseId
   if (!toolUseId) {
     span.setAttribute('ummaya.tui.primitive.error', 'missing_tool_use_id')
     span.end()
@@ -198,7 +198,7 @@ export async function dispatchPrimitive<O = unknown>(
         kind: 'tool_call',
         call_id: toolUseId,
         name: toolName,
-        arguments: opts.args,
+        arguments: argumentsForPrimitive(opts),
       }
 
       const sent = opts.bridge.send(toolCallFrame)
@@ -281,7 +281,7 @@ export async function dispatchPrimitive<O = unknown>(
   // Classification rules (all OR'd, evaluated against ``inner`` only):
   //   - ``inner.family === "mismatch_error"`` — VerifyMismatchError dump.
   //   - ``inner.kind === "error"`` — lookup / submit error sentinel.
-  //   - ``inner.reason ∈ FATAL_REASONS`` — defense-in-depth: any adapter that
+  //   - ``inner.reason ∈ FATAL_REASONS`` — defense-in-depth: an adapter that
   //     emits a known-fatal reason code is classified as failure even if it
   //     forgot to set ``kind``/``family``.
   const FATAL_REASONS = new Set([

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

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * UMMAYA — document-change → Claude Code diff-pipeline migration boundary.
+ *
+ * Deep-research-migration note (selected approach D):
+ *   specs/2802-public-doc-harness/deep-research-migration-document-render.md
+ *
+ * Document work renders in the TUI the same way Claude Code renders a code
+ * edit: automatically, inline, per-mutation, via `renderToolResultMessage`.
+ * Rather than invent a renderer, this module routes structural field-level
+ * document changes INTO the already-ported CC diff pipeline by representing the
+ * changed form as `label: value` text and producing the `StructuredPatchHunk[]`
+ * shape that `StructuredDiffList` already consumes byte-identically. The
+ * "structural" choice (difftastic / json-diff / daff convergence) is that the
+ * text is built from semantic fields, not from raw document bytes.
+ */
+import type { StructuredPatchHunk } from 'diff'
+import { getPatchFromContents } from '../../utils/diff.js'
+import type {
+  DocumentChangePayload,
+  DocumentDiffPayload,
+} from '../../components/primitive/types.js'
+
+/** Default inline cap; beyond this the inline view shows a "+N more" affordance. */
+export const DEFAULT_INLINE_CHANGE_CAP = 20
+
+export interface DocumentPatchResult {
+  /** Hunks ready for `<StructuredDiffList hunks={...} />` (CC pipeline). */
+  hunks: StructuredPatchHunk[]
+  /** Synthetic file path = document name; drives CC language detection. */
+  filePath: string
+  /** Actual visible changes after no-op entries are removed. */
+  changeCount: number
+  /** Changes actually rendered into the patch (≤ cap). */
+  renderedChangeCount: number
+  /** True when changes were dropped from the inline view, or the backend
+   *  already flagged inline truncation. */
+  truncated: boolean
+}
+
+interface DocumentChangeToPatchOptions {
+  documentName?: string
+  maxChanges?: number
+}
+
+export function documentChangeToPatch(
+  diff: DocumentDiffPayload,
+  options: DocumentChangeToPatchOptions = {},
+): DocumentPatchResult {
+  const filePath = nonEmpty(options.documentName) ?? 'document'
+  const cap = Math.max(0, options.maxChanges ?? DEFAULT_INLINE_CHANGE_CAP)
+  const changes = documentVisibleChanges(diff)
+  const changeCount = changes.length
+  const rendered = changes.slice(0, cap)
+  const renderedChangeCount = rendered.length
+  const truncated =
+    changeCount > renderedChangeCount || diff.inline_truncated === true
+
+  if (renderedChangeCount === 0) {
+    return { hunks: [], filePath, changeCount, renderedChangeCount, truncated }
+  }
+
+  // Trailing newline on both sides so the `diff` package does not emit a
+  // "" marker — that marker would also break the
+  // fallback renderer's remove/add adjacency pairing (and thus its word-level
+  // value highlighting).
+  const before = `${rendered.map((change) => fieldLine(change, 'before')).join('\n')}\n`
+  const after = `${rendered.map((change) => fieldLine(change, 'after')).join('\n')}\n`
+  const hunks = getPatchFromContents({
+    filePath,
+    oldContent: before,
+    newContent: after,
+    singleHunk: true,
+  })
+  return { hunks, filePath, changeCount, renderedChangeCount, truncated }
+}
+
+function fieldLine(change: DocumentChangePayload, side: 'before' | 'after'): string {
+  const fallbackLabel = humanizeDocumentTargetPath(change.target_path) || change.change_type
+  const label = nonEmpty(change.display_label) ?? fallbackLabel
+  const value = sanitizeValue(
+    side === 'before' ? change.before_value : change.after_value,
+  )
+  return `${label}: ${value}`
+}
+
+export function documentVisibleChanges(
+  diff: DocumentDiffPayload,
+): DocumentChangePayload[] {
+  return diff.changes.filter(hasVisibleChange)
+}
+
+function hasVisibleChange(change: DocumentChangePayload): boolean {
+  return sanitizeValue(change.before_value) !== sanitizeValue(change.after_value)
+}
+
+/**
+ * Structural path is the location (difftastic philosophy). Strip the leading
+ * slash and render nested segments with a breadcrumb separator so
+ * `/hwpx/text[12]` reads as `hwpx › text[12]`. No pixel coordinates — the field
+ * path is honest and precise about where the change lives.
+ */
+export function humanizeDocumentTargetPath(path: string): string {
+  const trimmed = path.trim().replace(/^\/+/u, '')
+  if (trimmed === '') {
+    return ''
+  }
+  return trimmed.replace(/\/+/gu, ' › ')
+}
+
+/** Collapse newlines so one field change stays one diff line. */
+function sanitizeValue(value: string | null | undefined): string {
+  if (value === null || value === undefined) {
+    return ''
+  }
+  return value.replace(/\r?\n/gu, ' ')
+}
+
+function nonEmpty(value: string | null | undefined): string | undefined {
+  if (value === null || value === undefined) {
+    return undefined
+  }
+  const trimmed = value.trim()
+  return trimmed === '' ? undefined : trimmed
+}

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

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+
+const DOCUMENT_READ_ONLY_OPERATIONS = new Set(['inspect', 'extract', 'validate'])
+
+type PrimitiveName = 'find' | 'locate' | 'check' | 'send' | 'document'
+
+export interface PrimitiveArgumentsOpts {
+  readonly primitive: PrimitiveName
+  readonly args: Record<string, unknown>
+  readonly context: {
+    readonly messages?: readonly unknown[]
+  }
+}
+
+export function argumentsForPrimitive(
+  opts: PrimitiveArgumentsOpts,
+): Record<string, unknown> {
+  if (opts.primitive !== 'document') return opts.args
+  if (isReadOnlyDocumentOperation(opts.args) && hasDocumentDispatchContract(opts.args)) {
+    return opts.args
+  }
+  const userQuery = latestUserTextFromContext(opts.context)
+  if (!userQuery) return opts.args
+  return {
+    ...opts.args,
+    __ummaya_user_query: userQuery,
+  }
+}
+
+function isReadOnlyDocumentOperation(args: Record<string, unknown>): boolean {
+  const operation = typeof args.operation === 'string'
+    ? args.operation.toLowerCase()
+    : 'fill'
+  return DOCUMENT_READ_ONLY_OPERATIONS.has(operation)
+}
+
+function hasDocumentDispatchContract(args: Record<string, unknown>): boolean {
+  const correlationId = args.correlation_id
+  const instruction = args.instruction
+  const document = recordFrom(args.document)
+  if (typeof correlationId !== 'string' || correlationId.trim() === '') return false
+  if (typeof instruction !== 'string' || instruction.trim() === '') return false
+  if (document === undefined) return false
+  const path = document.path
+  const artifactId = document.artifact_id
+  return (
+    (typeof path === 'string' && path.trim() !== '') ||
+    (typeof artifactId === 'string' && artifactId.trim() !== '')
+  )
+}
+
+function latestUserTextFromContext(context: PrimitiveArgumentsOpts['context']): string | undefined {
+  const messages = context.messages ?? []
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = recordFrom(messages[index])
+    if (message === undefined || message.type !== 'user') continue
+    const sdkMessage = recordFrom(message.message)
+    if (sdkMessage === undefined || sdkMessage.role !== 'user') continue
+    const content = sdkMessage.content
+    if (typeof content === 'string' && content.trim() !== '') {
+      return content
+    }
+    const text = textFromContentBlocks(content)
+    if (text !== undefined) return text
+  }
+  return undefined
+}
+
+function textFromContentBlocks(content: unknown): string | undefined {
+  if (!Array.isArray(content)) return undefined
+  const text = content
+    .map(block => {
+      const item = recordFrom(block)
+      if (item?.type !== 'text') return ''
+      return typeof item.text === 'string' ? item.text : ''
+    })
+    .filter(Boolean)
+    .join('\n')
+    .trim()
+  return text === '' ? undefined : text
+}
+
+function recordFrom(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : undefined
+}

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

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// UMMAYA-original — document primitive timeout policy.
+
+const DEFAULT_DOCUMENT_TIMEOUT_MS = 120_000
+
+export function resolveDocumentPrimitiveTimeoutMs(): number {
+  const env = process.env['UMMAYA_TUI_DOCUMENT_TIMEOUT_MS']
+  if (env) {
+    const parsed = Number.parseInt(env, 10)
+    if (Number.isFinite(parsed) && parsed > 0) return parsed
+  }
+  return DEFAULT_DOCUMENT_TIMEOUT_MS
+}

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

@@ -0,0 +1,98 @@
+import React from 'react'
+import { PrimitiveDispatcher } from '../../components/primitive/index.js'
+
+type DocumentRenderOptions = {
+  verbose?: boolean
+  isTranscriptMode?: boolean
+}
+
+/**
+ * Auto-render a document tool result inline in the TUI — the same way Claude
+ * Code renders a code diff after an edit, with no "show viewer" query. Driven
+ * by `renderToolResultMessage`, invoked by the message loop for every resolved
+ * tool result. See deep-research-migration-document-render.md (approach D).
+ */
+export function renderDocumentToolResultIfPresent(
+  output: unknown,
+  options: DocumentRenderOptions = {},
+): React.ReactNode | null {
+  const payload = extractDocumentToolResultPayload(output)
+  if (payload === null) {
+    return null
+  }
+  return React.createElement(PrimitiveDispatcher, {
+    payload,
+    expanded: options.verbose === true || options.isTranscriptMode === true,
+  })
+}
+
+/**
+ * Retired raster-availability gate.
+ *
+ * Previously this converted a successful `document_render` into a failure when
+ * a page raster was unreadable, because review happened in an external browser
+ * viewer that needed the image. Under deep-research-migration approach D the
+ * user surface is the structural field-level diff (`StructuredDiffList`), which
+ * renders from `diff.changes` and never depends on a raster — so the TUI no
+ * longer fabricates a visual-render failure. Page rasters remain Evidence
+ * Fabric evidence only (joinable by `correlation_id`).
+ *
+ * Kept as an identity pass-through so the model-facing primitive tools
+ * (AdapterTool / LookupPrimitive / SubmitPrimitive) keep a stable call boundary;
+ * full call-site removal is a tracked follow-up.
+ */
+export function applyDocumentVisualRenderGateToOutput(output: unknown): unknown {
+  return output
+}
+
+/** The TUI never fabricates a render failure under approach D; backend status
+ *  governs. Retained for call-boundary stability (see above). */
+export function isDocumentVisualRenderFailedOutput(_output: unknown): boolean {
+  return false
+}
+
+export function extractDocumentToolResultPayload(
+  output: unknown,
+): Record<string, unknown> | null {
+  const direct = asDocumentToolResultPayload(output)
+  if (direct !== null) {
+    return direct
+  }
+
+  const wrapped = asRecord(output)
+  if (wrapped === null) {
+    return null
+  }
+  return asDocumentToolResultPayload(wrapped.result)
+}
+
+function asDocumentToolResultPayload(output: unknown): Record<string, unknown> | null {
+  const record = asRecord(output)
+  if (record === null) {
+    return null
+  }
+  return (
+    typeof record.tool_id === 'string' &&
+    (record.tool_id === 'document' || record.tool_id.startsWith('document_')) &&
+    typeof record.correlation_id === 'string' &&
+    typeof record.text_summary === 'string' &&
+    isDocumentStatus(record.status)
+  )
+    ? record
+    : null
+}
+
+function isDocumentStatus(status: unknown): boolean {
+  return (
+    status === 'ok' ||
+    status === 'blocked' ||
+    status === 'failed' ||
+    status === 'needs_input'
+  )
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}

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

@@ -16,7 +16,7 @@ import type { ToolResultFrame } from '../../ipc/frames.generated.js'
 
 export interface PendingCall {
   callId: string
-  primitive: 'find' | 'locate' | 'check' | 'send'
+  primitive: 'find' | 'locate' | 'check' | 'send' | 'document'
   resolve: (frame: ToolResultFrame) => void
   reject: (err: Error) => void
   timeoutHandle: ReturnType<typeof setTimeout>
@@ -45,11 +45,6 @@ export interface PendingCall {
  */
 export class PendingCallRegistry {
   private _pending = new Map<string, PendingCall>()
-  // UMMAYA hotfix #2519 — race-safe buffering for ToolResultFrame frames
-  // that arrive BEFORE the matching dispatchPrimitive call has registered
-  // (the backend's _dispatch_primitive runs as a parallel asyncio.Task and
-  // can complete in <1s for cached / mock adapters, often beating the
-  // SDK's tool_use block parse → Tool.call() invocation timeline).
   private _buffered = new Map<string, ToolResultFrame>()
 
   /**

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

@@ -3,6 +3,7 @@ export const ROOT_PRIMITIVE_TOOL_IDS = new Set([
   'locate',
   'check',
   'send',
+  'document',
 ])
 
 function asRecord(value: unknown): Record<string, unknown> | null {

package/tui/src/tools/_shared/toolChoiceRepair/documentCompletionPatterns.ts

@@ -0,0 +1,58 @@
+export const DOCUMENT_TOOL_NAME = 'document'
+export const DOCUMENT_RENDER_TOOL_NAME = 'document_render'
+export type DocumentToolName =
+  | typeof DOCUMENT_TOOL_NAME
+  | typeof DOCUMENT_RENDER_TOOL_NAME
+
+export const DOCUMENT_COMPLETION_PROMPT_MARKER = 'Document primitive result complete'
+export const DOCUMENT_COMPLETION_PROMPT =
+  `${DOCUMENT_COMPLETION_PROMPT_MARKER}: the document tool_result for the latest citizen request is already visible in the TUI. Do not call another document, workspace, render, or tool-search tool in this turn. Answer in Korean only. Write the final Korean answer now from the actual tool_result only. Keep it to one or two short sentences: state whether the document was updated, blocked, failed, or needs explicit input; when the status is needs_input or the path is missing, ask the user to provide an exact existing file path or make an explicit selection; mention only changed field labels/values or required selection that are present in the visible diff; include the saved path only when the tool_result reports one. Do not invent units, parenthetical labels, workflow steps, style claims, or extra facts. Do not say an image, screenshot, viewport, render artifact, browser view, viewer, or visual artifact was generated. The inline TUI diff above is the user-visible proof.`
+export const DOCUMENT_INTENT_RE =
+  /(문서|공문서|양식|서식|파일|작성|저장|렌더|미리보기|변경사항|\bdiff\b|\bcompact\b|\bdocument\b|\bfile\b|\bform\b|\brender\b|\bsave\b|\bwrite\b)/iu
+export const DOCUMENT_WRITE_RE =
+  /(작성|수정|편집|채우|채워|입력|변경|저장|write|edit|fill|apply|save)/iu
+export const DOCUMENT_READ_ONLY_RE =
+  /(읽기\s*전용|수정\s*없이|변경\s*없이|저장\s*없이|수정하지\s*마|저장하지\s*마|작성하지\s*마|쓰지\s*마|열람만|확인만|inspect|extract|read\s*only)/iu
+export const DOCUMENT_DIFF_ONLY_FINAL_RE =
+  /(실제(?:로)?\s*바뀐\s*내용만|바뀐\s*내용만|변경된\s*부분만|변경사항만|actual\s+changed\s+content\s+only|only\s+changed)/iu
+export const DOCUMENT_DIFF_AND_SAVE_ONLY_FINAL_RE =
+  /(실제(?:로)?\s*바뀐\s*내용\s*(?:과|및|랑|하고)\s*저장\s*(?:위치|경로)만|변경(?:된)?\s*(?:내용|부분|사항).{0,24}저장\s*(?:위치|경로)만|changed.{0,24}(?:save|saved).{0,24}(?:location|path).{0,24}only)/iu
+const LOCAL_DOCUMENT_PATH_RE =
+  /(?:^|[\s"'(])((?:~|\/|\.{1,2}\/)[^\s"'<>]+?\.(?:hwpx|hwp|docx|pdf|xlsx|pptx))(?=$|[\s"'),.?!:;，。]|[가-힣])/iu
+const DOCUMENT_INSPECT_STRUCTURE_RE =
+  /(구조|빈칸|문항|양식|필드|항목|inspect|extract)/iu
+
+export type DocumentExpectedFormat =
+  | 'hwpx'
+  | 'hwp'
+  | 'docx'
+  | 'pdf'
+  | 'xlsx'
+  | 'pptx'
+
+export function localDocumentPathFromText(userText: string): string | undefined {
+  return LOCAL_DOCUMENT_PATH_RE.exec(userText)?.[1]
+}
+
+export function documentExpectedFormatFromPath(
+  path: string,
+): DocumentExpectedFormat | undefined {
+  const ext = path.split('.').pop()?.toLowerCase()
+  switch (ext) {
+    case 'hwpx':
+    case 'hwp':
+    case 'docx':
+    case 'pdf':
+    case 'xlsx':
+    case 'pptx':
+      return ext
+    default:
+      return undefined
+  }
+}
+
+export function isExactLocalReadOnlyDocumentPrompt(userText: string): boolean {
+  return localDocumentPathFromText(userText) !== undefined &&
+    (DOCUMENT_READ_ONLY_RE.test(userText) ||
+      DOCUMENT_INSPECT_STRUCTURE_RE.test(userText))
+}