Skip to content

The agent that grows with you

20.2 KB
Raw Blame
import type { ThreadMessage } from '@assistant-ui/react'
import type { ModelOptionsResult } from '@hermes/shared'
import { SLASH_COMMAND_RE } from '@hermes/shared'

import type { QuickModelOption } from '@/app/chat/composer/types'
import type { ClientSessionState } from '@/app/types'
import { formatRefValue } from '@/components/assistant-ui/directive-text'
import { type ChatMessage, type ChatMessagePart, chatMessageText, textPart } from '@/lib/chat-messages'
import { foldPersonalityName } from '@/lib/personalities'
import type { ComposerAttachment } from '@/store/composer'
import type { SessionInfo } from '@/types/hermes'

export { BUILTIN_PERSONALITIES } from '@/lib/personalities'

const THINKING_STATUS_PREFIX_RE =
  /^\s*(?:(?:[^\s.]{1,16})\s+)?(?:processing|thinking|reasoning|analyzing|pondering|contemplating|musing|cogitating|ruminating|deliberating|mulling|reflecting|computing|synthesizing|formulating|brainstorming)\.\.\.\s*/i

const EMPTY_THINKING_PLACEHOLDER_RE =
  /\b(?:current rewritten thinking|next thinking to process|provide the thinking content|don't see any .*thinking)\b/i

export function createClientSessionState(
  storedSessionId: string | null = null,
  messages: ChatMessage[] = []
): ClientSessionState {
  return {
    storedSessionId,
    messages,
    branch: '',
    cwd: '',
    model: '',
    provider: '',
    reasoningEffort: '',
    reasoningEffortWire: '',
    serviceTier: '',
    fast: false,
    yolo: false,
    personality: '',
    busy: false,
    awaitingResponse: false,
    streamId: null,
    sawAssistantPayload: false,
    adoptedRunningTurn: false,
    pendingBranchGroup: null,
    interrupted: false,
    interimBoundaryPending: false,
    needsInput: false,
    runtimeStartedAt: Date.now(),
    turnStartedAt: null,
    turnLive: false,
    usage: null
  }
}

/**
 * Mark a freshly resumed slice's effort as not-yet-known. The deferred-build
 * resume reply has no `reasoning_effort`, and falling through to the profile
 * default would paint a level the built agent's `session.info` then replaces
 * (#79807). A slice whose effort was already reported (a fast build can beat
 * the resume reply) keeps it.
 */
export function markReasoningEffortPending(state: ClientSessionState): ClientSessionState {
  return state.reasoningEffortPending === false ? state : { ...state, reasoningEffortPending: true }
}

export function sessionTitle(session: SessionInfo): string {
  return session.title?.trim() || session.preview?.trim() || 'Untitled session'
}

/** What a session is called before it has been sent — and before its composer
 *  has been typed into, which is the only thing that can name it earlier. */
export const NEW_SESSION_TITLE = 'New session'

export function coerceGatewayText(value: unknown): string {
  if (typeof value === 'string') {
    return value
  }

  if (value === null || value === undefined) {
    return ''
  }

  if (Array.isArray(value)) {
    return value
      .map(item => {
        if (typeof item === 'string') {
          return item
        }

        if (item && typeof item === 'object') {
          const row = item as Record<string, unknown>

          if (typeof row.text === 'string') {
            return row.text
          }

          if (typeof row.output_text === 'string') {
            return row.output_text
          }
        }

        return ''
      })
      .join('')
  }

  if (typeof value === 'object') {
    const row = value as Record<string, unknown>

    if (typeof row.text === 'string') {
      return row.text
    }

    if (typeof row.output_text === 'string') {
      return row.output_text
    }

    try {
      return JSON.stringify(value)
    } catch {
      return ''
    }
  }

  return String(value)
}

/**
 * Normalize a reasoning/thinking text payload from the gateway.
 *
 * Only the leading status prefix (e.g. "Hermes is thinking...") and the
 * obvious placeholder echoes are stripped. We deliberately do NOT trim
 * the delta — reasoning streams as small chunks (often individual tokens
 * with leading or trailing spaces), and trimming each chunk before
 * concatenation collapses adjacent words together. Whitespace between
 * tokens belongs to the data, not chrome.
 */
export function coerceThinkingText(value: unknown): string {
  const raw = coerceGatewayText(value).replace(THINKING_STATUS_PREFIX_RE, '')

  return EMPTY_THINKING_PLACEHOLDER_RE.test(raw) ? '' : raw
}

export function isImageGenerationTool(name?: string): boolean {
  return name === 'image_generate'
}

export function contextPath(path: string, cwd: string): string {
  if (!cwd) {
    return path
  }

  const normalizedCwd = cwd.endsWith('/') ? cwd : `${cwd}/`

  return path.startsWith(normalizedCwd) ? path.slice(normalizedCwd.length) : path
}

// IDs are content-derived (`kind:value`), not uuids, so upsertAttachment's
// exact-match dedupe only catches a re-attach when the raw value matches
// byte-for-byte. Normalize the value first so a trailing slash, a `\` path
// separator, etc. don't slip past dedupe as a "different" attachment.
function normalizeAttachmentValue(kind: ComposerAttachment['kind'], value: string): string {
  const trimmed = value.trim()

  if (kind === 'url') {
    try {
      // The WHATWG URL parser only collapses an EMPTY path to '/' (bare
      // origin) — it does not treat '/a' and '/a/' as equivalent, so strip a
      // trailing slash ourselves once the URL is otherwise canonicalized
      // (scheme/host case, default ports, etc.).
      return new URL(trimmed).toString().replace(/\/+$/, '')
    } catch {
      return trimmed
    }
  }

  if (kind === 'file' || kind === 'folder' || kind === 'image') {
    const posix = trimmed.replace(/\\/g, '/')

    // Don't collapse a bare root ('/' or 'C:/') down to an empty string.
    return posix.length > 1 ? posix.replace(/\/+$/, '') : posix
  }

  return trimmed
}

export function attachmentId(kind: ComposerAttachment['kind'], value: string): string {
  return `${kind}:${normalizeAttachmentValue(kind, value)}`
}

export function pathLabel(path: string): string {
  return path.split(/[\\/]/).filter(Boolean).pop() || path
}

export function attachmentDisplayText(attachment: ComposerAttachment): string | null {
  // Session switches / draft restores can leave undefined holes in the
  // composer attachments array (see AttachmentList's filter(Boolean) + #49624).
  // Every consumer funnels through here, so guard the chokepoint too.
  if (!attachment) {
    return null
  }

  if (attachment.kind === 'terminal' && attachment.detail) {
    return `\`\`\`terminal\n${attachment.detail.trim()}\n\`\`\``
  }

  if (attachment.refText) {
    return attachment.refText
  }

  if (attachment.kind === 'image') {
    const id = attachment.detail || attachment.path || attachment.label

    return id ? `@image:${formatRefValue(id)}` : null
  }

  return null
}

/**
 * Display ref for the optimistic (in-flight) user bubble.
 *
 * Images prefer their bounded base64 thumbnail over a file path. A raw `data:`
 * URL renders inline with zero network, while an `@image:<localpath>` ref would
 * route through `/api/media` and can 403 in remote mode. Full-resolution bytes
 * are loaded separately for the model and on-demand lightbox, not retained in
 * the optimistic message. `blob:` previews from OS drops bypass the data-URL
 * extract path and render as a markdown image instead (#63682).
 *
 * Everything else (files, folders, terminals, post-sync `@file:` refs) falls
 * through to `attachmentDisplayText`.
 */
export function optimisticAttachmentRef(attachment: ComposerAttachment): string | null {
  if (!attachment) {
    return null
  }

  if (attachment.kind === 'image') {
    // Object-URL previews from OS drops take precedence over the path ref:
    // markdown image keeps them out of the data-URL extract path while still
    // rendering inline in the optimistic bubble (#63682).
    if (attachment.previewUrl?.startsWith('blob:')) {
      // Percent-encode the alt text: a filename with `]` or parens in it would
      // otherwise break the Markdown-image form the directive parser matches
      // below, and the raw expression would leak into visible text (#123368).
      const alt = encodeURIComponent(attachment.label || 'image')

      return `![${alt}](${attachment.previewUrl})`
    }

    // Prefer a filesystem-backed `@image:<path>` ref so the in-flight bubble
    // renders through the same DirectiveImage path as a reloaded turn. That
    // component shows a bounded thumbnail inline (no full-resolution paint, so
    // the multi-image send freeze this design guards against does not return)
    // and hands the full-resolution file to the lightbox/download — fixing the
    // live-vs-reload fidelity gap where a sent screenshot stayed 512px until a
    // session reload rehydrated it (#93204). Remote gateways resolve the same
    // path over the authenticated media API, so no /api/media 403.
    const pathRef = attachment.path || attachment.detail

    if (pathRef) {
      return `@image:${formatRefValue(pathRef)}`
    }

    if (attachment.thumbnailUrl?.startsWith('data:')) {
      // No path to rehydrate from (e.g. pasted bytes): render the bounded
      // thumbnail inline. Full bytes remain available for the model upload.
      return attachment.thumbnailUrl
    }

    if (attachment.previewUrl?.startsWith('data:')) {
      // Backward compatibility for drafts created by older shells without a
      // separate thumbnail.
      return attachment.previewUrl
    }

    // A newly attached image with no path and no thumbnail yet: the queued
    // resize is still pending. Render nothing rather than paint the full source
    // and recreate the freeze if Send wins the race.
    return null
  }

  return attachmentDisplayText(attachment)
}

export function personalityNamesFromConfig(config: unknown): string[] {
  const root = config && typeof config === 'object' ? (config as Record<string, unknown>) : {}
  const agent = root.agent && typeof root.agent === 'object' ? (root.agent as Record<string, unknown>) : {}

  // The Python runtime (`hermes_cli.personality.available_personalities`) overlays
  // built-ins with the root-level `personalities` block, then `agent.personalities`
  // (agent wins on a name clash). Read both here so a root-registered persona the
  // CLI/gateway honour also reaches the GUI (#123297).
  // Fold each key the way the runtime does (`available_personalities`:
  // `str(name).strip().lower()`, dropping neutral spellings) so a case-variant,
  // whitespace-padded, or neutral-named block doesn't surface a row the runtime
  // can never resolve, and a root/agent case clash dedupes to one canonical name.
  const names = new Set<string>()

  for (const block of [root.personalities, agent.personalities]) {
    if (block && typeof block === 'object' && !Array.isArray(block)) {
      for (const name of Object.keys(block as Record<string, unknown>)) {
        const key = foldPersonalityName(name)

        if (key) {
          names.add(key)
        }
      }
    }
  }

  return [...names]
}

export function normalizePersonalityValue(value: string): string {
  // Share the runtime's canonical form with the dropdown reader (foldPersonalityName),
  // which also folds the `neutral` spelling this previously missed.
  return foldPersonalityName(value)
}

// Desktop prepends attachment ref tags (@image:, @file:, @url:, @folder:,
// @terminal:, @line:, @session:, @tool:, ...) to the submitted wire text. A
// slash command typed after those refs must still be detected — strip leading
// ref lines before testing the text for a command. Mirrors the gateway's
// _ATTACHMENT_REF_RE, but covers every ref kind the composer can emit.
const ATTACHMENT_REF_LINE_RE = /^@[a-z][a-z0-9-]*:[^\n]*\n?/i

export function stripAttachmentRefs(text: string): string {
  let current = text ?? ''

  while (true) {
    const next = current.replace(ATTACHMENT_REF_LINE_RE, '')

    if (next === current) {
      break
    }

    current = next
  }

  return current
}

export function isSlashCommandText(text: string): boolean {
  return SLASH_COMMAND_RE.test(stripAttachmentRefs(text).trimStart())
}

export function quickModelOptions(
  data: ModelOptionsResult | undefined,
  currentProvider: string,
  currentModel: string
): QuickModelOption[] {
  const seen = new Set<string>()
  const options: QuickModelOption[] = []

  const providers = [...(data?.providers ?? [])].sort((a, b) => {
    if (a.slug === currentProvider) {
      return -1
    }

    if (b.slug === currentProvider) {
      return 1
    }

    if (a.is_current) {
      return -1
    }

    if (b.is_current) {
      return 1
    }

    return 0
  })

  const add = (provider: string, providerName: string, model: string) => {
    const key = `${provider}:${model}`

    if (!model || seen.has(key)) {
      return
    }

    seen.add(key)
    options.push({ provider, providerName, model })
  }

  if (currentProvider && currentModel) {
    add(currentProvider, currentProvider, currentModel)
  }

  for (const provider of providers) {
    const models = [...(provider.models ?? [])].sort((a, b) => {
      if (provider.slug === currentProvider && a === currentModel) {
        return -1
      }

      if (provider.slug === currentProvider && b === currentModel) {
        return 1
      }

      return 0
    })

    for (const model of models) {
      add(provider.slug, provider.name, model)
    }

    if (options.length >= 8) {
      break
    }
  }

  return options.slice(0, 8)
}

// A message's display time. `timestamp` (Unix seconds) is authoritative when
// present. Without it we fall back to *now* rather than digging digits out of
// the id: message ids come in incompatible shapes — `assistant-<ms>`,
// `<seconds>-<i>-<role>`, session-style `20260728_184420_…` — and feeding any
// of them to `new Date()` (which reads ms) lands on the 1970 epoch, rendering
// as an absurd "20663d ago". A timestamp-less message is a freshly created
// optimistic/streaming one, so *now* is the right age anyway.
export function messageCreatedAt(message: Pick<ChatMessage, 'timestamp'>, nowMs = Date.now()): Date {
  return typeof message.timestamp === 'number' && Number.isFinite(message.timestamp) && message.timestamp > 0
    ? new Date(message.timestamp * 1000)
    : new Date(nowMs)
}

export function toRuntimeMessage(message: ChatMessage): ThreadMessage {
  const role =
    message.role === 'user' || message.role === 'assistant' || message.role === 'system' ? message.role : 'assistant'

  const createdAt = messageCreatedAt(message)

  // Reactions and the durable row id ride metadata.custom for every role — the
  // established channel for per-message extras (attachmentRefs below).
  const reactionMeta = {
    ...(message.rowId !== undefined ? { rowId: message.rowId } : {}),
    ...(message.reactions?.length ? { reactions: message.reactions } : {})
  }

  const timelineMeta =
    typeof message.timestamp === 'number' && Number.isFinite(message.timestamp) && message.timestamp > 0
      ? { timelineTimestamp: message.timestamp }
      : {}

  if (role === 'user') {
    return {
      id: message.id,
      role,
      content: message.parts.filter((part): part is Extract<ChatMessagePart, { type: 'text' }> => part.type === 'text'),
      attachments: [],
      createdAt,
      metadata: { custom: { attachmentRefs: message.attachmentRefs ?? [], ...reactionMeta, ...timelineMeta } }
    } as ThreadMessage
  }

  if (role === 'system') {
    const text = chatMessageText(message)

    return {
      id: message.id,
      role,
      content: [textPart(text)],
      createdAt,
      metadata: {
        custom: {
          ...timelineMeta,
          ...(message.asyncResult ? { asyncResult: message.asyncResult } : {}),
          ...(message.asyncResultKind ? { asyncResultKind: message.asyncResultKind } : {})
        }
      }
    } as ThreadMessage
  }

  return {
    id: message.id,
    role,
    content: message.parts as Extract<ThreadMessage, { role: 'assistant' }>['content'],
    createdAt,
    status: message.error
      ? { type: 'incomplete', reason: 'error', error: message.error }
      : message.pending
        ? { type: 'running' }
        : { type: 'complete', reason: 'stop' },
    metadata: {
      unstable_state: null,
      unstable_annotations: [],
      unstable_data: [],
      steps: [],
      // Carries ChatMessage.interim to AssistantMessage's footer gate.
      custom: {
        ...(message.interim ? { interim: true } : {}),
        ...(message.interrupted ? { interrupted: true } : {}),
        ...timelineMeta,
        ...(message.completedAt !== undefined ? { timelineCompletedAt: message.completedAt } : {}),
        ...(message.durationS !== undefined ? { durationS: message.durationS } : {}),
        // Structured failure layer for the error card (see lib/error-surface).
        ...(message.errorSurface ? { errorSurface: message.errorSurface } : {}),
        ...reactionMeta
      }
    }
  } as ThreadMessage
}

export type ToolMergeCache = WeakMap<
  ChatMessage,
  { merged: ChatMessage; parts: ChatMessagePart[]; prev: ChatMessage; prevParts: ChatMessagePart[] }
>

export function createToolMergeCache(): ToolMergeCache {
  return new WeakMap()
}

// A settled assistant message with only tool calls — no prose, no reasoning.
// The model routinely emits a follow-up batch of calls as its own text-less
// message; on screen it looks like one continuous run, but assistant-ui can't
// group tool calls across a message boundary.
function isToolOnlyAssistant(message: ChatMessage): boolean {
  return (
    message.role === 'assistant' &&
    !message.pending &&
    !message.error &&
    !message.hidden &&
    message.parts.length > 0 &&
    message.parts.every(part => part.type === 'tool-call')
  )
}

/**
 * Concatenate a tool-only follow-up message's parts onto its predecessor's,
 * dropping any incoming `tool-call` part whose `toolCallId` the predecessor
 * already carries. A repeated id here is the SAME call re-attached (structural
 * carry-over re-adding a cached row's tool calls, or a live-turn projection
 * that also exists as a committed row — #87857): folding both copies into one
 * message manufactures the duplicate key that crashes assistant-ui's
 * `useResources`, and renaming it would render the same call twice. Genuinely
 * new calls in the same follow-up row are preserved.
 */
export function concatToolPartsUnique(
  prevParts: readonly ChatMessagePart[],
  nextParts: readonly ChatMessagePart[]
): ChatMessagePart[] {
  const seen = new Set<string>()

  for (const part of prevParts) {
    if (part.type === 'tool-call' && part.toolCallId) {
      seen.add(part.toolCallId)
    }
  }

  const out = [...prevParts]

  for (const part of nextParts) {
    if (part.type === 'tool-call' && part.toolCallId) {
      if (seen.has(part.toolCallId)) {
        continue
      }

      seen.add(part.toolCallId)
    }

    out.push(part)
  }

  return out
}

/**
 * Fold each settled tool-only assistant message into the preceding assistant
 * message so its calls join that message's tool group (and can collapse into
 * the auto-scrolling window). Render-only — never mutates the `$messages` store
 * — and settle-only: pending messages are left alone, so a live turn is never
 * merged/un-merged mid-stream. `cache` keys merged results by source identity,
 * so a stable turn yields stable merged objects (no re-render churn).
 */
export function coalesceToolOnlyAssistants(messages: ChatMessage[], cache: ToolMergeCache): ChatMessage[] {
  const out: ChatMessage[] = []

  for (const message of messages) {
    const prev = out.at(-1)

    if (prev && prev.role === 'assistant' && !prev.pending && !prev.hidden && isToolOnlyAssistant(message)) {
      const cached = cache.get(message)

      const merged =
        cached && cached.prev === prev && cached.prevParts === prev.parts && cached.parts === message.parts
          ? cached.merged
          : {
              ...prev,
              completedAt: [prev.completedAt, message.completedAt, ...message.parts.map(part => part.completedAt)]
                .filter((value): value is number => value !== undefined)
                .reduce<number | undefined>(
                  (latest, value) => (latest === undefined ? value : Math.max(latest, value)),
                  undefined
                ),
              parts: concatToolPartsUnique(prev.parts, message.parts)
            }

      cache.set(message, { merged, parts: message.parts, prev, prevParts: prev.parts })
      out[out.length - 1] = merged

      continue
    }

    out.push(message)
  }

  return out
}