@shawnstack/quickforge 1.4.1 → 1.5.1

package/server/routes/scheduled-tasks.mjs

@@ -585,11 +585,7 @@ async function executeTask(task, trigger = 'schedule', onStarted) {
   let sessionId = `scheduled-${task.id}-${Date.now().toString(36)}`
   let executionAgent = null
   let agentWarning = null
-  if (task.agentId) {
-    executionAgent = await getAgentProfile(task.agentId)
-    if (!executionAgent) agentWarning = `Configured agent not found: ${task.agentId}`
-  }
-  const agentSnapshot = executionAgent ? agentProfileSnapshot(executionAgent) : null
+  let agentSnapshot = null
 
   let started = false
   await updateTask(task.id, (current) => {
@@ -630,6 +626,11 @@ async function executeTask(task, trigger = 'schedule', onStarted) {
 
   try {
     const executionProject = await resolveExecutionProject(task)
+    if (task.agentId) {
+      executionAgent = await getAgentProfile(task.agentId, { projectId: executionProject?.id || null, workspaceRoot: executionProject?.path })
+      if (!executionAgent) agentWarning = `Configured agent not found: ${task.agentId}`
+    }
+    agentSnapshot = executionAgent ? agentProfileSnapshot(executionAgent) : null
     const settings = await readStore('settings')
     const yoloMode = settings?.['yolo-mode'] === true || settings?.['yolo-mode'] === 'true'
 

package/server/routes/storage.mjs

@@ -5,6 +5,7 @@ import { directorySize } from '../utils/workspace.mjs'
 
 const metadataIndexCache = new Map()
 const MAX_METADATA_INDEX_CACHE_ENTRIES = 50
+const METADATA_INDEX_CACHE_TTL_MS = 1000
 
 function metadataIndexCacheKey({ scope, projectId, indexName, direction }) {
   return JSON.stringify({ scope: scope || '', projectId: projectId || '', indexName, direction })
@@ -47,7 +48,8 @@ async function readIndexedValues(store, indexName, direction, scope, projectId)
   const revision = getStoreRevision(store)
   const key = metadataIndexCacheKey({ scope, projectId, indexName, direction })
   const cached = metadataIndexCache.get(key)
-  if (cached && cached.revision === revision) return cached.values
+  const now = Date.now()
+  if (cached && cached.revision === revision && now - cached.cachedAt < METADATA_INDEX_CACHE_TTL_MS) return cached.values
 
   const data = scope
     ? await readSessionStoreScoped(store, scope, scope === 'project' ? projectId : undefined)
@@ -59,7 +61,7 @@ async function readIndexedValues(store, indexName, direction, scope, projectId)
     direction,
   )
 
-  metadataIndexCache.set(key, { revision, values })
+  metadataIndexCache.set(key, { revision, values, cachedAt: now })
   if (metadataIndexCache.size > MAX_METADATA_INDEX_CACHE_ENTRIES) {
     const firstKey = metadataIndexCache.keys().next().value
     if (firstKey) metadataIndexCache.delete(firstKey)

package/server/routes/system.mjs

@@ -2,6 +2,33 @@ import { sendJson, readJsonBody } from '../utils/response.mjs'
 import { getLanUrls } from '../utils/network.mjs'
 
 export async function handleSystemApi(req, res, url, context) {
+  if (req.method === 'GET' && url.pathname === '/api/system/about') {
+    sendJson(res, 200, await context.getPackageInfo())
+    return
+  }
+
+  if (req.method === 'GET' && url.pathname === '/api/system/update/check') {
+    sendJson(res, 200, await context.checkForUpdates())
+    return
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/system/update') {
+    if (!context.isLocalRequest) {
+      const error = new Error('Update is only allowed from this computer')
+      error.statusCode = 403
+      throw error
+    }
+
+    if (req.headers['x-quickforge-action'] !== 'update') {
+      const error = new Error('Forbidden action')
+      error.statusCode = 403
+      throw error
+    }
+
+    sendJson(res, 200, await context.updateQuickForge())
+    return
+  }
+
   if (req.method === 'POST' && url.pathname === '/api/system/restart') {
     if (req.headers['x-quickforge-action'] !== 'restart') {
       const error = new Error('Forbidden action')

package/server/routes/tools.mjs

@@ -4,6 +4,7 @@ import { toolHandlers, loadSkillToolContext } from '../tools/index.mjs'
 import { createSkillTools, workspaceTools } from '../tools/definitions.mjs'
 import { createMcpToolDefinitions } from '../mcp/registry.mjs'
 import { callPluginTool, createPluginToolDefinitions, isPluginToolName } from '../plugins/registry.mjs'
+import { safeReadTools } from '../approval-store.mjs'
 import { projectContextFromId, readProjectConfig } from '../project-config.mjs'
 
 const directRouteDisabledTools = new Set(['run_subagent'])
@@ -26,13 +27,22 @@ export async function handleGetTools(_req, res) {
 
 const workspaceToolNames = new Set(workspaceTools.map((tool) => tool.name))
 
-async function assertYoloEnabledForTool(name) {
-  if (!workspaceToolNames.has(name)) return
+function normalizeAccessMode(value, fallback = 'default') {
+  if (value === 'default' || value === 'full-access') return value
+  if (value === true || value === 'true') return 'full-access'
+  if (value === false || value === 'false') return 'default'
+  if (fallback !== value) return normalizeAccessMode(fallback, 'default')
+  return 'default'
+}
+
+async function assertAccessModeAllowsDirectTool(name) {
+  const protectedTool = workspaceToolNames.has(name) || isPluginToolName(name)
+  if (!protectedTool || safeReadTools.has(name)) return
 
   const settings = await readStore('settings')
-  const yoloMode = settings?.['yolo-mode'] === true || settings?.['yolo-mode'] === 'true'
-  if (!yoloMode) {
-    const error = new Error('YOLO mode is disabled. Enable it to use this tool.')
+  const accessMode = normalizeAccessMode(settings?.['agent-access-mode'], settings?.['yolo-mode'])
+  if (accessMode !== 'full-access') {
+    const error = new Error('Full access permission is required to execute this tool directly.')
     error.statusCode = 403
     throw error
   }
@@ -74,6 +84,7 @@ export async function handleToolApi(req, res, url) {
   }
 
   if (isPluginToolName(name)) {
+    await assertAccessModeAllowsDirectTool(name)
     const params = await readJsonBody(req)
     const result = await callPluginTool(name, params || {}, context)
     sendJson(res, 200, result)
@@ -87,7 +98,7 @@ export async function handleToolApi(req, res, url) {
     throw error
   }
 
-  await assertYoloEnabledForTool(name)
+  await assertAccessModeAllowsDirectTool(name)
 
   const params = await readJsonBody(req)
   const result = await handler(params || {}, context)

package/server/routes/workspace.mjs

@@ -5,15 +5,15 @@ import { sendJson, readJsonBody } from '../utils/response.mjs'
 import { projectContextFromId } from '../project-config.mjs'
 import {
   assertSafeWorkspacePath,
-  isSensitiveWorkspacePath,
   resolveWorkspacePath,
-  shouldSearchFile,
   toWorkspaceRelative,
 } from '../utils/workspace.mjs'
 
-const MAX_PREVIEW_BYTES = 1024 * 1024
-const MAX_TREE_NODES = 5000
-const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', 'dist-ssr', 'package-dist', 'package-offline', '.vite', 'coverage'])
+const MAX_PREVIEW_BYTES = 50 * 1024 * 1024
+const MAX_STATIC_PREVIEW_BYTES = 50 * 1024 * 1024
+const PREVIEW_ALLOWED_EXTENSIONS = new Set(['.html', '.htm', '.css', '.js', '.mjs', '.json', '.svg', '.png', '.jpg', '.jpeg', '.webp', '.gif', '.ico', '.txt', '.md'])
+const MAX_TREE_NODES = 50000
+const SKIP_DIRS = new Set(['.git', 'node_modules'])
 
 const extensionLanguageMap = new Map([
   ['ts', 'typescript'], ['tsx', 'typescript'], ['js', 'javascript'], ['jsx', 'javascript'],
@@ -34,12 +34,26 @@ function languageFromPath(filePath) {
   return extensionLanguageMap.get(extension) || 'plaintext'
 }
 
-function isBinaryBuffer(buffer) {
-  const length = Math.min(buffer.length, 8000)
-  for (let index = 0; index < length; index += 1) {
-    if (buffer[index] === 0) return true
+function previewContentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase()
+  const map = {
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.txt': 'text/plain; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
   }
-  return false
+  return map[ext] || 'application/octet-stream'
 }
 
 async function projectContextFromUrl(url) {
@@ -144,10 +158,71 @@ function countGitStatus(files) {
   }, { staged: 0, unstaged: 0, untracked: 0, conflicts: 0, total: 0 })
 }
 
+function countTextLines(text) {
+  if (text.length === 0) return 0
+  return text.split('\n').length - (text.endsWith('\n') ? 1 : 0)
+}
+
+// numstat 的路径列对 rename 用 "prefix/{old => new}" 或 "old => new" 形式，取新路径
+function numstatNewPath(rawPath) {
+  const arrow = rawPath.indexOf(' => ')
+  if (arrow < 0) return rawPath
+  const head = rawPath.slice(0, arrow)
+  const tail = rawPath.slice(arrow + 4)
+  const brace = head.lastIndexOf('{')
+  if (brace < 0) return tail
+  return `${head.slice(0, brace)}${tail.replace(/\}$/, '')}`
+}
+
+// 工作区 vs HEAD 的每个文件增删行数（口径与 git diff --numstat 一致）
+async function collectNumstat(context) {
+  const map = new Map()
+  const result = await git(['diff', 'HEAD', '--numstat', '-z'], context.workspaceRoot, { allowFailure: true })
+  if (result.code !== 0) return map
+  const records = result.stdout.toString('utf8').split('\0').filter(Boolean)
+  for (const record of records) {
+    const fields = record.split('\t')
+    if (fields.length < 3) continue
+    const added = fields[0]
+    const removed = fields[1]
+    const rawPath = fields.slice(2).join('\t')
+    if (added === '-' || removed === '-') continue // 二进制文件
+    const additions = Number(added)
+    const deletions = Number(removed)
+    if (!Number.isFinite(additions) || !Number.isFinite(deletions)) continue
+    map.set(numstatNewPath(rawPath), { additions, deletions })
+  }
+  return map
+}
+
+// 未跟踪文件不在 numstat 中，按工作区文件行数估算新增行
+async function countWorkspaceLines(context, relativePath) {
+  try {
+    const { content } = await readWorkspaceTextFile(context, relativePath)
+    return countTextLines(content)
+  } catch {
+    return undefined
+  }
+}
+
 async function listGitStatus(context) {
   if (!(await isGitRepository(context.workspaceRoot))) return { isGitRepository: false, files: [] }
   const result = await git(['status', '--porcelain=v1', '-z'], context.workspaceRoot)
   const files = parseGitStatus(result.stdout)
+  const numstat = await collectNumstat(context)
+  for (const file of files) {
+    const entry = numstat.get(file.path)
+    if (entry) {
+      file.additions = entry.additions
+      file.deletions = entry.deletions
+    } else if (file.status === 'untracked' || file.status === 'added') {
+      const count = await countWorkspaceLines(context, file.path)
+      if (typeof count === 'number') {
+        file.additions = count
+        file.deletions = 0
+      }
+    }
+  }
   return {
     isGitRepository: true,
     branch: await currentGitBranch(context.workspaceRoot),
@@ -163,7 +238,7 @@ async function readGitFile(workspaceRoot, ref, relativePath) {
 
 async function readWorkspaceTextFile(context, relativePath) {
   const file = resolveWorkspacePath(relativePath, context)
-  await assertSafeWorkspacePath(file, context)
+  await assertSafeWorkspacePath(file, context, { allowSensitive: true })
   const stat = await fs.stat(file)
   if (!stat.isFile()) {
     const error = new Error('Path is not a file')
@@ -176,11 +251,6 @@ async function readWorkspaceTextFile(context, relativePath) {
     throw error
   }
   const buffer = await fs.readFile(file)
-  if (isBinaryBuffer(buffer)) {
-    const error = new Error('Binary file cannot be previewed')
-    error.statusCode = 415
-    throw error
-  }
   return { content: buffer.toString('utf8'), size: stat.size, path: toWorkspaceRelative(file, context) }
 }
 
@@ -197,9 +267,9 @@ async function buildTreeForDirectory(dir, context, counter) {
     const fullPath = path.join(dir, entry.name)
     const relativePath = toWorkspaceRelative(fullPath, context)
     if (entry.isDirectory()) {
-      if (SKIP_DIRS.has(entry.name) || isSensitiveWorkspacePath(fullPath, context)) continue
+      if (SKIP_DIRS.has(entry.name)) continue
       try {
-        await assertSafeWorkspacePath(fullPath, context)
+        await assertSafeWorkspacePath(fullPath, context, { allowSensitive: true })
         counter.count += 1
         nodes.push({
           name: entry.name,
@@ -211,9 +281,8 @@ async function buildTreeForDirectory(dir, context, counter) {
         // Skip directories that cannot be safely resolved.
       }
     } else if (entry.isFile()) {
-      if (!shouldSearchFile(entry.name) || isSensitiveWorkspacePath(fullPath, context)) continue
       try {
-        await assertSafeWorkspacePath(fullPath, context)
+        await assertSafeWorkspacePath(fullPath, context, { allowSensitive: true })
         counter.count += 1
         nodes.push({ name: entry.name, path: relativePath, type: 'file' })
       } catch {
@@ -246,6 +315,55 @@ async function handleWorkspaceFile(req, res, url) {
   })
 }
 
+async function handleWorkspacePreview(req, res, url) {
+  const prefix = '/api/workspace/preview/'
+  const tail = url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) : ''
+  const slashIndex = tail.indexOf('/')
+  if (slashIndex <= 0) {
+    const error = new Error('projectId and path are required')
+    error.statusCode = 400
+    throw error
+  }
+
+  const projectId = decodeURIComponent(tail.slice(0, slashIndex))
+  const relativePath = decodeURIComponent(tail.slice(slashIndex + 1))
+  if (!projectId || !relativePath) {
+    const error = new Error('projectId and path are required')
+    error.statusCode = 400
+    throw error
+  }
+
+  const context = await projectContextFromId(projectId)
+  const file = resolveWorkspacePath(relativePath, context)
+  await assertSafeWorkspacePath(file, context)
+  const extension = path.extname(file).toLowerCase()
+  if (!PREVIEW_ALLOWED_EXTENSIONS.has(extension)) {
+    const error = new Error('Unsupported preview file type')
+    error.statusCode = 415
+    throw error
+  }
+  const stat = await fs.stat(file)
+  if (!stat.isFile()) {
+    const error = new Error('Path is not a file')
+    error.statusCode = 400
+    throw error
+  }
+  if (stat.size > MAX_STATIC_PREVIEW_BYTES) {
+    const error = new Error('File is too large to preview')
+    error.statusCode = 413
+    throw error
+  }
+
+  const contentType = previewContentType(file)
+  res.writeHead(200, {
+    'content-type': contentType,
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+  })
+  const buffer = await fs.readFile(file)
+  res.end(buffer)
+}
+
 async function handleWorkspaceResolvePath(req, res) {
   const body = await readJsonBody(req, 16 * 1024)
   const projectId = typeof body?.projectId === 'string' ? body.projectId : ''
@@ -344,6 +462,10 @@ export async function handleWorkspaceApi(req, res, url) {
     await handleWorkspaceFile(req, res, url)
     return
   }
+  if (req.method === 'GET' && url.pathname.startsWith('/api/workspace/preview/')) {
+    await handleWorkspacePreview(req, res, url)
+    return
+  }
   if (req.method === 'POST' && url.pathname === '/api/workspace/resolve-path') {
     await handleWorkspaceResolvePath(req, res)
     return

package/server/session-utils.mjs

@@ -1,5 +1,5 @@
 import { streamSimple } from '@earendil-works/pi-ai'
-import { buildInstructionsPayload } from './project-config.mjs'
+import { buildInstructionsPayload, projectContextFromId } from './project-config.mjs'
 import { composeSystemPrompt } from './system-prompt.mjs'
 import { listSubagentProfiles } from './agent-profiles.mjs'
 
@@ -9,9 +9,17 @@ import { listSubagentProfiles } from './agent-profiles.mjs'
 
 export async function buildSystemPrompt(projectId) {
   const instructions = await buildInstructionsPayload(projectId)
+  let workspaceRoot = instructions.workspace?.root || null
+  if (projectId && !workspaceRoot) {
+    try {
+      workspaceRoot = (await projectContextFromId(projectId))?.workspaceRoot || null
+    } catch {
+      // project may have been removed; fall back to global agent profile discovery
+    }
+  }
   return composeSystemPrompt({
     ...instructions,
-    subagents: await listSubagentProfiles(),
+    subagents: await listSubagentProfiles({ projectId, workspaceRoot }),
   })
 }
 

package/server/storage.mjs

@@ -468,6 +468,26 @@ async function rebuildBucketIndex() {
   bucketIndexBuilt = true
 }
 
+async function findSessionBucketByDataFile(sessionId) {
+  assertSafePathSegment(sessionId)
+  const buckets = [
+    { scope: 'global' },
+    ...(await listProjectIds()).map((projectId) => ({ scope: 'project', projectId })),
+  ]
+
+  for (const bucket of buckets) {
+    const file = sessionDataFile(sessionId, bucket)
+    try {
+      const stat = await fs.stat(file)
+      if (stat.isFile()) return bucket
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error
+    }
+  }
+
+  return null
+}
+
 export async function findSessionBucket(sessionId) {
   if (!bucketIndexBuilt) {
     await ensureStorage()
@@ -478,8 +498,12 @@ export async function findSessionBucket(sessionId) {
 
 export async function readSessionValue(sessionId) {
   const bucket = await findSessionBucket(sessionId)
-  if (!bucket) return null
-  return readJsonFile(sessionDataFile(sessionId, bucket), null)
+  if (bucket) return readJsonFile(sessionDataFile(sessionId, bucket), null)
+
+  const recoveredBucket = await findSessionBucketByDataFile(sessionId)
+  if (!recoveredBucket) return null
+  sessionBucketIndex.set(sessionId, recoveredBucket)
+  return readJsonFile(sessionDataFile(sessionId, recoveredBucket), null)
 }
 
 export async function writeSessionValue(sessionId, value) {
@@ -725,6 +749,9 @@ export function ensureStorage() {
       fs.mkdir(path.join(cacheDir, 'projects'), { recursive: true }),
       fs.mkdir(path.join(storageDir, 'conversations', 'global', 'sessions'), { recursive: true }),
       fs.mkdir(path.join(storageDir, 'conversations', 'projects'), { recursive: true }),
+      // Default workspace directory for global (non-project) conversations, so
+      // they share the same file-tool capabilities as project conversations.
+      fs.mkdir(path.join(dataDir, 'workspace'), { recursive: true }),
       cleanOldLogs(),
     ])
 

package/server/system-prompt.mjs

@@ -5,6 +5,7 @@ For project tasks:
 - Prefer the simplest solution that satisfies the request.
 - Make surgical changes only. Do not refactor unrelated code.
 - Match existing style.
+- When content has room for visual explanation, first consider whether an SVG diagram can improve understanding.
 - For multi-step work, use a brief plan.
 - Before changing files, gather sufficient context: relevant files, entry points or call chains, existing patterns, tests or validation commands, and docs/wiki impact.
 - Before taking action, confirm with the user.

package/server/tools/definitions.mjs

@@ -86,6 +86,24 @@ export const workspaceTools = [
     }),
     executionMode: 'sequential',
   },
+  {
+    name: 'present_files',
+    label: 'Present files',
+    description: 'Show one or more AI-produced artifact files to the user. Use this after creating or editing user-facing files such as HTML pages, SVG/images, Markdown documents, or other deliverables. HTML files will be previewed directly in the artifact preview panel.',
+    parameters: Type.Object({
+      files: Type.Array(Type.Union([
+        Type.String({ description: 'File path relative to the workspace root.' }),
+        Type.Object({
+          path: Type.String({ description: 'File path relative to the workspace root.' }),
+          title: Type.Optional(Type.String({ description: 'Optional display title.' })),
+          description: Type.Optional(Type.String({ description: 'Optional short description shown in artifact lists.' })),
+          kind: Type.Optional(Type.String({ description: 'Optional file kind hint, such as html, image, markdown, or code.' })),
+          preview: Type.Optional(Type.Boolean({ description: 'Whether this file should be opened as the default preview.' })),
+        }),
+      ]), { description: 'Artifact files to present.' }),
+      defaultPreview: Type.Optional(Type.String({ description: 'File path to open as the default preview when multiple files are presented.' })),
+    }),
+  },
 ]
 
 function activeSkillSchema(skills) {

package/server/tools/index.mjs

@@ -619,6 +619,91 @@ export async function toolReadSkillResource(params, context) {
   }
 }
 
+// --- present_files ---
+function inferPresentedFileKind(relativePath) {
+  const lower = String(relativePath || '').toLowerCase()
+  if (lower.endsWith('.html') || lower.endsWith('.htm')) return 'html'
+  if (/\.(svg|png|jpe?g|webp|gif|bmp|ico)$/.test(lower)) return 'image'
+  if (lower.endsWith('.md') || lower.endsWith('.mdx')) return 'markdown'
+  if (/\.(ts|tsx|js|jsx|mjs|cjs|css|scss|less|json|jsonc|txt|xml|yml|yaml|toml|ini|py|rb|go|rs|java|c|h|cpp|hpp|cs|php|sh|bash|zsh|ps1)$/.test(lower)) return 'code'
+  return 'unknown'
+}
+
+function normalizePresentFileEntry(entry) {
+  if (typeof entry === 'string') return { path: entry }
+  if (entry && typeof entry === 'object' && typeof entry.path === 'string') {
+    return {
+      path: entry.path,
+      title: typeof entry.title === 'string' ? entry.title : undefined,
+      description: typeof entry.description === 'string' ? entry.description : undefined,
+      kind: typeof entry.kind === 'string' ? entry.kind : undefined,
+      preview: typeof entry.preview === 'boolean' ? entry.preview : undefined,
+    }
+  }
+  return undefined
+}
+
+export async function toolPresentFiles(params, context) {
+  const rawFiles = Array.isArray(params?.files) ? params.files : []
+  const defaultPreviewInput = typeof params?.defaultPreview === 'string' ? params.defaultPreview : undefined
+  if (rawFiles.length === 0) {
+    const error = new Error('files must contain at least one path')
+    error.statusCode = 400
+    throw error
+  }
+
+  const files = []
+  const seen = new Set()
+  for (const raw of rawFiles) {
+    const entry = normalizePresentFileEntry(raw)
+    if (!entry?.path?.trim()) continue
+    const file = resolveWorkspacePath(entry.path, context)
+    await assertSafeWorkspacePath(file, context)
+    const stat = await fs.stat(file)
+    if (!stat.isFile()) {
+      const error = new Error(`Path is not a file: ${entry.path}`)
+      error.statusCode = 400
+      throw error
+    }
+    const relativePath = toWorkspaceRelative(file, context)
+    const key = relativePath.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    const kind = entry.kind || inferPresentedFileKind(relativePath)
+    const isDefaultPreview = defaultPreviewInput ? relativePath === defaultPreviewInput.replace(/\\/g, '/') : false
+    // 所有已知 kind 均自动预览（与前端 isPreviewablePath 语义一致）：调用 present_files 即自动打开 tab。
+    // 渲染路径由前端按 kind 决定：html/image → browser iframe；markdown/code → 侧栏渲染。
+    const autoPreviewable = kind !== 'unknown'
+    files.push({
+      path: relativePath,
+      title: entry.title,
+      description: entry.description,
+      kind,
+      preview: entry.preview ?? (isDefaultPreview || autoPreviewable),
+      defaultPreview: isDefaultPreview,
+      bytes: stat.size,
+    })
+  }
+
+  if (files.length === 0) {
+    const error = new Error('No valid files to present')
+    error.statusCode = 400
+    throw error
+  }
+
+  const previewed = files.filter((file) => file.preview).map((file) => file.path)
+  return {
+    content: `Presented ${files.length} file(s)${previewed.length ? ` and opened ${previewed.length} preview(s)` : ''}: ${files.map((file) => file.path).join(', ')}`,
+    details: {
+      type: 'present_files_result',
+      files,
+      defaultPreview: files.find((file) => file.defaultPreview)?.path,
+      previewed,
+      project: context?.project,
+    },
+  }
+}
+
 // --- run_command ---
 const DEFAULT_RUN_COMMAND_TIMEOUT_MS = 30 * 60 * 1000
 const MIN_RUN_COMMAND_TIMEOUT_MS = 1000
@@ -1009,6 +1094,7 @@ export const toolHandlers = {
   write_file: toolWriteFile,
   edit_file: toolEditFile,
   run_command: toolRunCommand,
+  present_files: toolPresentFiles,
   activate_skill: toolActivateSkill,
   read_skill_resource: toolReadSkillResource,
 }