Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
11.3 KB
Raw Blame
import { createHash, randomUUID } from 'node:crypto'
import { chmod, lstat, mkdir, readdir, rename, rm, stat, utimes, writeFile } from 'node:fs/promises'
import { extname, join } from 'node:path'
import {
  ATTACHMENT_MAX_FILE_BYTES,
  ATTACHMENT_TEXT_EXCERPT_BYTES,
  normalizeAttachments,
  type AttachmentDescriptor,
} from '../../../../shared/attachments.js'
import { normalizeStorageKey } from '../../storage-keys.js'
import type { VisionCapability } from './model-capabilities.js'

const DOWNLOAD_TIMEOUT_MS = 20_000
export const ATTACHMENT_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000
export const ATTACHMENT_CACHE_MAX_BYTES = 1024 * 1024 * 1024

export interface AttachmentCacheOptions {
  readonly maxAgeMs?: number
  readonly maxBytes?: number
  readonly now?: () => number
}

export interface AttachmentCacheCleanupResult {
  readonly removedFiles: number
  readonly removedBytes: number
  readonly remainingBytes: number
}

export interface CachedAttachment {
  readonly attachment: AttachmentDescriptor
  readonly path: string
  readonly text?: string
  readonly textTruncated?: boolean
}

export interface AttachmentCacheResult {
  readonly files: readonly CachedAttachment[]
  readonly failures: ReadonlyArray<{ name: string; reason: string; key?: string }>
}

export function isImageAttachment(attachment: AttachmentDescriptor): boolean {
  return attachment.kind === 'img' || attachment.mime?.startsWith('image/') === true
}

function safeName(name: string): string {
  const base = name.normalize('NFKC').replace(/[\\/\u0000-\u001f\u007f]/g, '_').trim()
  const cleaned = base.replace(/^\.+/, '').replace(/[<>:"|?*]/g, '_').slice(0, 160)
  return cleaned || 'attachment'
}

function textual(mime: string | undefined): boolean {
  const normalized = mime?.toLowerCase() ?? ''
  return normalized.startsWith('text/') || [
    'application/json', 'application/x-yaml', 'application/x-toml',
    'application/xml', 'application/javascript', 'application/sql',
  ].includes(normalized)
}

async function ensureCacheDirectory(path: string): Promise<void> {
  try {
    await mkdir(path, { recursive: true, mode: 0o700 })
  } catch (error) {
    const code = (error as NodeJS.ErrnoException).code
    if (code !== 'EEXIST') throw error
  }
  const info = await lstat(path)
  if (!info.isDirectory() || info.isSymbolicLink()) {
    throw new Error('attachment cache path is not a private directory')
  }
  await chmod(path, 0o700)
}

/** Download every attachment through the runtime JWT endpoint into this
 *  agent's home. The model never receives the bearer token or chooses a URL. */
export class AgentAttachmentCache {
  private readonly activePaths = new Set<string>()
  private turnDepth = 0
  private readonly maxAgeMs: number
  private readonly maxBytes: number
  private readonly now: () => number

  constructor(
    private readonly homeRoot: string,
    private readonly serverUrl: string,
    private readonly getToken: () => Promise<string>,
    private readonly fetchImpl: typeof fetch = fetch,
    options: AttachmentCacheOptions = {},
  ) {
    this.maxAgeMs = options.maxAgeMs ?? ATTACHMENT_CACHE_MAX_AGE_MS
    this.maxBytes = options.maxBytes ?? ATTACHMENT_CACHE_MAX_BYTES
    this.now = options.now ?? Date.now
    if (!Number.isFinite(this.maxAgeMs) || this.maxAgeMs < 0) {
      throw new Error('attachment cache maxAgeMs must be a non-negative finite number')
    }
    if (!Number.isFinite(this.maxBytes) || this.maxBytes < 0) {
      throw new Error('attachment cache maxBytes must be a non-negative finite number')
    }
  }

  /** Mark paths produced during a model turn as live. Cleanup never removes
   * them until the corresponding turn has finished. */
  beginTurn(): void {
    this.turnDepth += 1
  }

  /** Release the current-turn protection and run the bounded local cleanup. */
  async endTurn(): Promise<AttachmentCacheCleanupResult> {
    this.turnDepth = Math.max(0, this.turnDepth - 1)
    if (this.turnDepth > 0) {
      return this.cleanup()
    }
    this.activePaths.clear()
    const result = await this.cleanup()
    return result
  }

  /** Reap expired and least-recently-used files under this Agent's home.
   * Symlinks and directories are never followed. Active turn paths are
   * protected even when the cache is over its size limit. */
  async cleanup(): Promise<AttachmentCacheCleanupResult> {
    const root = join(this.homeRoot, 'attachments')
    const entries: Array<{ path: string; size: number; atimeMs: number }> = []
    try {
      const messages = await readdir(root, { withFileTypes: true })
      for (const message of messages) {
        if (!message.isDirectory() || message.isSymbolicLink()) continue
        const directory = join(root, message.name)
        const files = await readdir(directory, { withFileTypes: true }).catch((error: unknown) => {
          if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
          throw error
        })
        for (const file of files) {
          if (!file.isFile() || file.isSymbolicLink()) continue
          const path = join(directory, file.name)
          try {
            const info = await stat(path)
            if (!info.isFile()) continue
            entries.push({ path, size: info.size, atimeMs: Math.max(info.atimeMs, info.mtimeMs) })
          } catch (error) {
            if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
          }
        }
      }
    } catch (error) {
      const code = (error as NodeJS.ErrnoException).code
      if (code !== 'ENOENT' && code !== 'ENOTDIR') throw error
      return { removedFiles: 0, removedBytes: 0, remainingBytes: 0 }
    }

    const now = this.now()
    const expired = entries.filter((entry) =>
      !this.activePaths.has(entry.path) && now - entry.atimeMs >= this.maxAgeMs,
    )
    const candidates = entries
      .filter((entry) => !this.activePaths.has(entry.path) && !expired.includes(entry))
      .sort((a, b) => a.atimeMs - b.atimeMs)
    const expiredPaths = new Set(expired.map((entry) => entry.path))
    let remainingBytes = entries.reduce((sum, entry) => sum + entry.size, 0)
    const remove = [...expired, ...candidates]
    let removedFiles = 0
    let removedBytes = 0
    for (const entry of remove) {
      if (!expiredPaths.has(entry.path) && remainingBytes <= this.maxBytes) break
      try {
        await rm(entry.path, { force: true })
        removedFiles += 1
        removedBytes += entry.size
        remainingBytes -= entry.size
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
      }
    }
    return { removedFiles, removedBytes, remainingBytes: Math.max(0, remainingBytes) }
  }

  /** Sweep after the runner has stopped. Persistent engine sessions may still
   * refer to paths from earlier turns, so keep unexpired files unless the
   * owning Agent is being removed. */
  async dispose(options: { purge?: boolean } = {}): Promise<void> {
    this.activePaths.clear()
    this.turnDepth = 0
    if (options.purge) {
      await rm(join(this.homeRoot, 'attachments'), { recursive: true, force: true })
      return
    }
    await this.cleanup()
  }

  async materialize(messageId: string, value: unknown): Promise<AttachmentCacheResult> {
    await this.cleanup()
    const safeMessage = messageId.replace(/[^a-z0-9._-]/gi, '_').slice(0, 160) || createHash('sha256')
      .update(messageId).digest('hex').slice(0, 16)
    const directory = join(this.homeRoot, 'attachments', safeMessage)
    await ensureCacheDirectory(join(this.homeRoot, 'attachments'))
    await ensureCacheDirectory(directory)
    const token = await this.getToken()
    const files: CachedAttachment[] = []
    const failures: Array<{ name: string; reason: string; key?: string }> = []

    for (const [index, attachment] of normalizeAttachments(value).entries()) {
      const key = normalizeStorageKey(attachment.key ?? '')
      if (!key?.startsWith('attachments/')) {
        failures.push({ name: attachment.name, reason: 'missing trusted Cumora attachment key' })
        continue
      }
      try {
        const target = new URL(
          `${this.serverUrl.replace(/\/+$/, '')}/runtime/attachment?key=${encodeURIComponent(key)}&messageId=${encodeURIComponent(messageId)}`,
        )
        const response = await this.fetchImpl(
          target,
          {
            headers: { Authorization: `Bearer ${token}` },
            redirect: 'follow',
            signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
          },
        )
        if (!response.ok) throw new Error(`HTTP ${response.status}`)
        const declared = Number(response.headers.get('content-length') ?? 0)
        if (declared > ATTACHMENT_MAX_FILE_BYTES) throw new Error('attachment exceeds 25 MiB')
        const bytes = Buffer.from(await response.arrayBuffer())
        if (bytes.length === 0) throw new Error('attachment is empty')
        if (bytes.length > ATTACHMENT_MAX_FILE_BYTES) throw new Error('attachment exceeds 25 MiB')
        const extension = extname(safeName(attachment.name)).replace(/[^.a-z0-9]/gi, '').slice(0, 16)
        const file = join(directory, `${index + 1}-${createHash('sha256').update(key).digest('hex').slice(0, 16)}${extension}`)
        const staged = `${file}.${process.pid}.${randomUUID()}.tmp`
        try {
          await writeFile(staged, bytes, { mode: 0o600, flag: 'wx' })
          await chmod(staged, 0o600).catch(() => {})
          await rename(staged, file)
        } finally {
          await rm(staged, { force: true }).catch(() => {})
        }
        if (this.turnDepth > 0) this.activePaths.add(file)
        // Keep the local file's access time fresh for LRU cleanup. This is
        // best effort because some filesystems disable atime updates.
        await utimes(file, new Date(), new Date()).catch(() => {})
        files.push({
          attachment,
          path: file,
          ...(textual(attachment.mime) ? {
            text: bytes.subarray(0, ATTACHMENT_TEXT_EXCERPT_BYTES).toString('utf8'),
            textTruncated: bytes.length > ATTACHMENT_TEXT_EXCERPT_BYTES,
          } : {}),
        })
      } catch (error) {
        failures.push({ name: attachment.name, key, reason: error instanceof Error ? error.message : 'download failed' })
      }
    }
    return { files, failures }
  }
}

export function attachmentImageGuidance(vision: VisionCapability): string {
  if (vision === 'supported') {
    return 'This image is in your Agent home. Use native image input or image viewing on this path before relying on visual details.'
  }
  if (vision === 'unsupported') {
    return 'The active model does not support image input. Do not claim to have seen this image.'
  }
  return 'Visual support is unknown. If you have a native image viewer, use the local path to inspect this image. Do not claim to have seen it unless image viewing succeeds.'
}

export function renderCachedAttachments(result: AttachmentCacheResult, vision: VisionCapability): string {
  const lines: string[] = []
  for (const file of result.files) {
    lines.push(`Attachment "${file.attachment.name}": ${file.path}`)
    if (isImageAttachment(file.attachment)) {
      lines.push(attachmentImageGuidance(vision))
    }
    if (file.text !== undefined) {
      lines.push(`File excerpt${file.textTruncated ? ' (first 50 KiB)' : ''}:`, '```', file.text, '```')
    }
  }
  for (const failure of result.failures) {
    lines.push(`Attachment "${failure.name}" could not be downloaded: ${failure.reason}`)
  }
  return lines.join('\n')
}