Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
21.2 KB
Raw Blame
/**
 * WorkspaceService — filesystem-backed document store.
 *
 * All operations are scoped to the workspace root directory.
 * Path safety: rejects absolute paths, ".." traversal, and null bytes.
 */
import { Mutex } from 'async-mutex'
import * as fs from 'fs/promises'
import * as path from 'path'
import type { PersonalizationConfig } from '../types'
import {
  GfsDownloadPathError,
  isProtectedGfsRealPath,
  isProtectedRealPath,
  isProtectedWorkspacePath,
  protectedWorkspacePathError,
} from './protectedPaths'
import { scanWriteContent } from './scanner'
import { searchWorkspace } from './search'
import { SearchConfig, SearchResult, WorkspaceEntry } from './types'

function todayDate(): string {
  return new Date().toISOString().slice(0, 10)
}

// Case-sensitive by design: these are the exact root-level filenames mcp-host
// reconciles from Host.spec.personalization. Lowercase variants are not
// friendly-blocked here; filesystem permissions still provide the OS backstop.
export const LOCKED_IDENTITY_FILES: ReadonlySet<string> = new Set([
  'IDENTITY.md',
  'SOUL.md',
  'AGENTS.md',
  'USER.md',
])

export function adminManagedIdentityFileMessage(filename: string): string {
  return `${filename} is admin-managed and cannot be modified by the agent. Contact your admin to update it.`
}

export class LockedFileError extends Error {
  constructor(filename: string) {
    super(adminManagedIdentityFileMessage(filename))
    this.name = 'LockedFileError'
  }
}

/**
 * Normalize a relative path to its canonical root-level form so we can compare
 * against LOCKED_IDENTITY_FILES exactly. Rejects anything that — after
 * normalization — is the bare basename of a locked file at workspace root.
 *
 * Returns true for: "IDENTITY.md", "./IDENTITY.md", "/IDENTITY.md", "IDENTITY.md/", etc.
 * Returns false for: "agents.md" (case), "daily/AGENTS.md" (sub-path), "AGENTS.md.bak".
 */
export function isLockedPath(relativePath: string): boolean {
  if (typeof relativePath !== 'string' || relativePath.length === 0) return false
  // path.posix.normalize handles "./", "//", "/.", trailing-".".
  // Then strip leading "/" and "./", and trailing "/".
  let normalized = path.posix.normalize(relativePath)
  if (normalized.startsWith('./')) normalized = normalized.slice(2)
  if (normalized.startsWith('/')) normalized = normalized.slice(1)
  if (normalized.endsWith('/')) normalized = normalized.slice(0, -1)
  return LOCKED_IDENTITY_FILES.has(normalized)
}

export {
  GfsDownloadPathError,
  StateDbPathError,
  isStateDbName,
  isStateDbPath,
  stateDbProtectedMessage,
} from './protectedPaths'

/**
 * Agent-facing workspace surface, implemented by both {@link WorkspaceService}
 * (the flat Pod-wide store) and `ScopedWorkspace` (the per-user routing view).
 * Consumers that receive an injected workspace (memory tools, context manager,
 * prompt assembly) depend on this interface so a scoped view is a drop-in.
 * Collective-only operations (`applyAdminIdentityFiles`, `listAll`) are NOT on
 * the interface — they live on `WorkspaceService` and run on the collective root.
 */
export interface Workspace {
  read(relativePath: string): Promise<string | null>
  write(relativePath: string, content: string): Promise<void>
  append(relativePath: string, content: string): Promise<void>
  delete(relativePath: string): Promise<void>
  exists(relativePath: string): Promise<boolean>
  list(directory?: string): Promise<WorkspaceEntry[]>
  search(query: string, limit?: number): Promise<SearchResult[]>
  readMemory(): Promise<string>
  appendMemory(entry: string): Promise<void>
  readPrivateMemory(): Promise<string>
  appendPrivateMemory(entry: string): Promise<void>
  writePrivateMemory(content: string): Promise<void>
  readTodayLog(): Promise<string>
  appendDailyLog(entry: string): Promise<void>
  readHeartbeatChecklist(): Promise<string | null>
  readIdentityFiles(): Promise<{ identity: string; soul: string; agents: string; user: string }>
  snapshotDailyLogs(days?: number): Promise<string>
  assembleSystemPrompt(): Promise<string>
}

export class WorkspaceService implements Workspace {
  // Per-file mutex keyed by absolute resolved path. Ensures concurrent
  // writes/appends from different sessions don't interleave and that the
  // read-modify-write inside append() is transactional.
  private readonly fileMutexes = new Map<string, Mutex>()

  constructor(
    private readonly workspacePath: string,
    // Top-level dir names skipped by `list('')`/`listAll`/`search` — used so the
    // collective instance never enumerates or scans `users/` (per-user subtrees).
    private readonly options?: { excludeDirs?: readonly string[] }
  ) {}

  /** Absolute root this service is confined to (used to scope raw file tools). */
  get rootPath(): string {
    return this.workspacePath
  }

  // ── Path safety ────────────────────────────────────────────────────────────

  private resolvePath(relativePath: string): string {
    if (relativePath.includes('\0')) {
      throw new Error('Path contains null bytes')
    }
    if (path.isAbsolute(relativePath)) {
      throw new Error('Absolute paths not allowed')
    }
    if (relativePath.includes('..')) {
      throw new Error('Directory traversal (..) not allowed')
    }
    // Normalize: strip leading slash, collapse duplicate slashes
    const normalized = relativePath.replace(/\/+/g, '/').replace(/^\//, '')
    const resolved = path.resolve(this.workspacePath, normalized)
    // Containment via path.relative (not startsWith, which has a prefix-collision
    // bug: "/a/ws" would match a sibling "/a/ws-evil"). This matters once the
    // service is rooted at a per-user subtree. A symlink inside the root can
    // still redirect out — that residual is bundled with shell sandboxing.
    const rel = path.relative(this.workspacePath, resolved)
    if (rel.startsWith('..') || path.isAbsolute(rel)) {
      throw new Error('Path resolves outside workspace')
    }
    return resolved
  }

  /**
   * Resolve an agent-requested path and reject aliases into platform-owned
   * storage. The lexical guard blocks direct names; realpath checks block a
   * symlink or missing file whose nearest existing ancestor points into the
   * protected namespace or outside the workspace.
   */
  private async resolveAccessiblePath(relativePath: string): Promise<string> {
    if (isProtectedWorkspacePath(relativePath)) {
      throw protectedWorkspacePathError(relativePath)
    }
    const resolved = this.resolvePath(relativePath)
    const realWorkspaceRoot = await fs.realpath(this.workspacePath)
    let current = resolved
    while (current !== path.dirname(current)) {
      try {
        const realPath = await fs.realpath(current)
        const relative = path.relative(realWorkspaceRoot, realPath)
        if (relative.startsWith('..') || path.isAbsolute(relative)) {
          throw new Error('Path resolves outside workspace')
        }
        if (isProtectedRealPath(realPath, realWorkspaceRoot)) {
          throw isProtectedGfsRealPath(realPath)
            ? new GfsDownloadPathError(path.relative(realWorkspaceRoot, realPath))
            : protectedWorkspacePathError(path.relative(realWorkspaceRoot, realPath))
        }
        break
      } catch (err) {
        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
        current = path.dirname(current)
      }
    }
    return resolved
  }

  private mutexFor(absolutePath: string): Mutex {
    let m = this.fileMutexes.get(absolutePath)
    if (!m) {
      m = new Mutex()
      this.fileMutexes.set(absolutePath, m)
    }
    return m
  }

  // ── Document CRUD ──────────────────────────────────────────────────────────

  async read(relativePath: string): Promise<string | null> {
    const resolved = await this.resolveAccessiblePath(relativePath)
    try {
      return await fs.readFile(resolved, 'utf-8')
    } catch {
      return null
    }
  }

  async write(relativePath: string, content: string): Promise<void> {
    if (isLockedPath(relativePath)) {
      throw new LockedFileError(relativePath)
    }
    const resolved = await this.resolveAccessiblePath(relativePath)
    scanWriteContent(relativePath, content, Buffer.byteLength(content, 'utf-8'))
    await this.mutexFor(resolved).runExclusive(async () => {
      await this._atomicWrite(resolved, content)
    })
  }

  /**
   * `opts.scan === false` skips the prompt-feeding injection scan. Used ONLY by
   * `appendDailyLog` for the compaction archive (F3): that content is raw
   * conversation that already passed through the model, not a fresh injection
   * vector, and legitimate conversation (security discussions, pastes, quoted
   * prompts) trips the patterns — scanning it would silently drop legitimate
   * archives. Deliberate agent writes to `daily/*` (memory_write) use the
   * default-scanned path.
   */
  async append(relativePath: string, content: string, opts?: { scan?: boolean }): Promise<void> {
    if (isLockedPath(relativePath)) {
      throw new LockedFileError(relativePath)
    }
    const resolved = await this.resolveAccessiblePath(relativePath)
    await this.mutexFor(resolved).runExclusive(async () => {
      let existing: string | null
      try {
        existing = await fs.readFile(resolved, 'utf-8')
      } catch {
        existing = null
      }
      const separator = existing ? '\n' : ''
      const next = (existing ?? '') + separator + content
      if (opts?.scan !== false) {
        scanWriteContent(relativePath, next, Buffer.byteLength(next, 'utf-8'))
      }
      await this._atomicWrite(resolved, next)
    })
  }

  async delete(relativePath: string): Promise<void> {
    if (isLockedPath(relativePath)) {
      throw new LockedFileError(relativePath)
    }
    await fs.unlink(await this.resolveAccessiblePath(relativePath))
  }

  /**
   * Atomic write via temp file + rename. Crash- and race-safe: readers always
   * see either the previous content or the new content, never a partial one.
   * On any I/O failure, the temp file is best-effort cleaned up.
   */
  private async _atomicWrite(
    resolved: string,
    content: string,
    opts?: { chmod?: number }
  ): Promise<void> {
    const dir = path.dirname(resolved)
    const base = path.basename(resolved)
    const tempPath = path.join(
      dir,
      `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`
    )
    try {
      await fs.mkdir(dir, { recursive: true })
      await fs.writeFile(tempPath, content, 'utf-8')
      if (opts?.chmod !== undefined) {
        await fs.chmod(tempPath, opts.chmod)
      }
      await fs.rename(tempPath, resolved)
    } catch (err) {
      await fs.rm(tempPath, { force: true }).catch(() => undefined)
      throw err
    }
  }

  async exists(relativePath: string): Promise<boolean> {
    try {
      await fs.access(await this.resolveAccessiblePath(relativePath))
      return true
    } catch {
      return false
    }
  }

  // ── Directory listing ──────────────────────────────────────────────────────

  async list(directory: string = ''): Promise<WorkspaceEntry[]> {
    let resolved: string
    if (directory) {
      resolved = await this.resolveAccessiblePath(directory)
    } else {
      const realRoot = await fs.realpath(this.workspacePath)
      if (isProtectedRealPath(realRoot, realRoot)) {
        throw isProtectedGfsRealPath(realRoot)
          ? new GfsDownloadPathError(path.basename(realRoot))
          : protectedWorkspacePathError(path.basename(realRoot))
      }
      resolved = this.workspacePath
    }
    let entries: { name: string; isDirectory(): boolean }[]
    try {
      entries = await fs.readdir(resolved, { withFileTypes: true })
    } catch {
      return []
    }

    const realWorkspaceRoot = await fs.realpath(this.workspacePath)
    const results: WorkspaceEntry[] = []
    for (const entry of entries) {
      if (isProtectedWorkspacePath(entry.name)) continue
      // At the root, skip excluded top-level dirs (e.g. `users/` on collective).
      if (!directory && this.options?.excludeDirs?.includes(entry.name)) continue
      const entryPath = path.join(directory, entry.name).replace(/^\//, '')
      const absPath = path.join(resolved, entry.name)
      // A symlink with a harmless name can resolve to store data; the listing
      // omits it as read and write already deny it. A dangling link reaches no
      // file and stays listed. A link that cannot be resolved (a loop, a path
      // through a file) is omitted without hiding its siblings.
      if (await this.omitFromListing(absPath, realWorkspaceRoot)) continue
      let size: number | undefined
      let modifiedAt: string | undefined
      try {
        const stat = await fs.stat(absPath)
        size = stat.size
        modifiedAt = stat.mtime.toISOString()
      } catch {
        // ignore stat errors
      }
      results.push({
        name: entry.name,
        path: entryPath,
        type: entry.isDirectory() ? 'directory' : 'file',
        size,
        modifiedAt,
      })
    }
    return results
  }

  private async omitFromListing(absPath: string, realWorkspaceRoot: string): Promise<boolean> {
    let realPath: string
    try {
      realPath = await fs.realpath(absPath)
    } catch (err) {
      return (err as NodeJS.ErrnoException).code !== 'ENOENT'
    }
    return isProtectedRealPath(realPath, realWorkspaceRoot)
  }

  async listAll(): Promise<string[]> {
    const { searchWorkspace: collect } = await import('./search')
    // Reuse the internal file collector by doing a dummy search with empty result
    const files: string[] = []
    const entries = await this.list()
    const recurse = async (dir: string) => {
      const children = await this.list(dir)
      for (const child of children) {
        if (child.type === 'directory') {
          await recurse(child.path)
        } else {
          files.push(child.path)
        }
      }
    }
    for (const entry of entries) {
      if (entry.type === 'directory') {
        await recurse(entry.path)
      } else {
        files.push(entry.path)
      }
    }
    return files
  }

  // ── Search ─────────────────────────────────────────────────────────────────

  async search(query: string, limit: number = 10): Promise<SearchResult[]> {
    return searchWorkspace(this.workspacePath, query, { limit }, this.options?.excludeDirs)
  }

  // ── Convenience methods ────────────────────────────────────────────────────

  async readMemory(): Promise<string> {
    return (await this.read('MEMORY.md')) ?? ''
  }

  async appendMemory(entry: string): Promise<void> {
    await this.append('MEMORY.md', entry)
  }

  // ── Private (per-user) memory (F5) ──────────────────────────────────────────
  // A flat WorkspaceService has no per-user dimension, so private memory
  // degenerates to its single MEMORY.md. In production the injected workspace is
  // a ScopedWorkspace, which routes these to the per-user root
  // (`users/<userKey>/MEMORY.md`). MEMORY.md content is NOT injected into the
  // system prompt — the agent recalls it via memory_search / memory_read.
  async readPrivateMemory(): Promise<string> {
    return this.readMemory()
  }

  async appendPrivateMemory(entry: string): Promise<void> {
    await this.appendMemory(entry)
  }

  async writePrivateMemory(content: string): Promise<void> {
    await this.write('MEMORY.md', content)
  }

  async readTodayLog(): Promise<string> {
    return (await this.read(`daily/${todayDate()}.md`)) ?? ''
  }

  async appendDailyLog(entry: string): Promise<void> {
    const now = new Date().toISOString().slice(11, 19) // HH:MM:SS
    // scan:false — this is the compaction-archive path (raw conversation that
    // already passed through the model). Deliberate agent writes to daily use
    // `append('daily/...')` directly (memory_write) and ARE scanned. See F3.
    await this.append(`daily/${todayDate()}.md`, `[${now}] ${entry}`, { scan: false })
  }

  async readHeartbeatChecklist(): Promise<string | null> {
    const content = await this.read('HEARTBEAT.md')
    if (!content) return null

    // Empty detection: only whitespace, HTML comments, headers, or empty checkboxes
    const stripped = content
      .replace(/<!--[\s\S]*?-->/g, '') // strip HTML comments
      .replace(/^#+\s.*$/gm, '') // strip markdown headers
      .replace(/^\s*-\s*\[\s*\]\s*.*$/gm, '') // strip empty checkboxes
      .trim()

    return stripped.length > 0 ? content : null
  }

  // ── T2.2 — Tiered system prompt helpers ────────────────────────────────────

  /**
   * Read the four locked identity files as separate strings (instead of the
   * pre-concatenated form `assembleSystemPrompt()` returns). T2.2 needs them
   * individually so the `stable` tier can format each section with a header
   * and skip the empty ones cleanly. Returns the empty string for any file
   * that does not exist or is unreadable — identical semantics to the legacy
   * loader.
   */
  async readIdentityFiles(): Promise<{
    identity: string
    soul: string
    agents: string
    user: string
  }> {
    const [identity, soul, agents, user] = await Promise.all([
      this.read('IDENTITY.md').then(c => c ?? ''),
      this.read('SOUL.md').then(c => c ?? ''),
      this.read('AGENTS.md').then(c => c ?? ''),
      this.read('USER.md').then(c => c ?? ''),
    ])
    return { identity, soul, agents, user }
  }

  /**
   * Read the last `days` daily logs (today first) and concatenate them with
   * absolute date headers. Empty or missing days are omitted. T2.2 freezes
   * the resulting string at session start so mid-session writes to
   * `daily/<today>.md` do NOT re-flow into the cached `stable` tier.
   *
   * Labels are absolute (`## 2026-05-22 Notes`) rather than relative
   * (`Today`/`Yesterday`) because the snapshot survives the session lifetime
   * and may outlive midnight — a frozen "Today's Notes" header would lie
   * about the date of the underlying file once the calendar day rolls.
   */
  async snapshotDailyLogs(days: number = 2): Promise<string> {
    const parts: string[] = []
    const today = new Date()
    for (let i = 0; i < days; i++) {
      const d = new Date(today.getTime() - i * 86400000)
      const date = d.toISOString().slice(0, 10)
      const content = await this.read(`daily/${date}.md`)
      if (content && content.trim().length > 0) {
        parts.push(`## ${date} Notes\n\n${content.trim()}`)
      }
    }
    return parts.join('\n\n---\n\n')
  }

  // ── System prompt assembly ─────────────────────────────────────────────────

  async assembleSystemPrompt(): Promise<string> {
    const parts: string[] = []

    const identityFiles: [string, string][] = [
      ['AGENTS.md', '## Agent Instructions'],
      ['SOUL.md', '## Core Values'],
      ['USER.md', '## User Context'],
      ['IDENTITY.md', '## Identity'],
    ]

    for (const [filePath, header] of identityFiles) {
      const content = await this.read(filePath)
      if (content && content.trim().length > 0) {
        parts.push(`${header}\n\n${content.trim()}`)
      }
    }

    // Include last 2 days of daily logs
    const today = todayDate()
    const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10)

    for (const [date, label] of [
      [today, "Today's Notes"],
      [yesterday, "Yesterday's Notes"],
    ] as const) {
      const content = await this.read(`daily/${date}.md`)
      if (content && content.trim().length > 0) {
        parts.push(`## ${label}\n\n${content.trim()}`)
      }
    }

    return parts.join('\n\n---\n\n')
  }

  // ── Identity file reconciliation (admin-managed) ───────────────────────────

  /**
   * Reconcile the four locked identity files from a PersonalizationConfig.
   *
   * For each file:
   *   - Non-empty field → overwrite the file with that content.
   *   - Empty / undefined / null field → truncate the file to empty.
   *
   * Each file is left chmod 0o444 after writing, so any non-privileged caller
   * that bypasses the workspace lock check gets EACCES from the OS.
   *
   * Idempotent. No-op when config is null/undefined.
   */
  async applyAdminIdentityFiles(config: PersonalizationConfig | null | undefined): Promise<void> {
    if (!config) return
    await fs.mkdir(this.workspacePath, { recursive: true })
    const files: Array<[string, string | undefined]> = [
      ['IDENTITY.md', config.identity],
      ['SOUL.md', config.soul],
      ['AGENTS.md', config.agents],
      ['USER.md', config.user],
    ]
    for (const [filename, content] of files) {
      const resolved = this.resolvePath(filename)
      await this.mutexFor(resolved).runExclusive(async () => {
        await this._atomicWrite(resolved, content ?? '', { chmod: 0o444 })
      })
    }
  }
}