@shawnstack/quickforge 1.7.4 → 1.7.6

package/server/cloud/service-config.mjs

@@ -0,0 +1,81 @@
+import { atomicUpdate, readStore } from '../storage.mjs'
+import { parseCloudBaseUrl } from './config.mjs'
+
+export const CLOUD_SERVICE_SETTINGS_KEY = 'quickforge-cloud-service'
+export const CLOUD_SERVICE_SCHEMA_VERSION = 1
+export const CLOUD_SERVICE_TYPE = 'quickforge-cloud'
+export const DEFAULT_CLOUD_URL = 'http://127.0.0.1:8082/'
+
+function savedServiceRecord(settings) {
+  const value = settings?.[CLOUD_SERVICE_SETTINGS_KEY]
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined
+}
+
+function candidateFrom(settings, env) {
+  const saved = savedServiceRecord(settings)
+  if (saved && typeof saved.cloudUrl === 'string' && saved.cloudUrl.trim()) {
+    return { value: saved.cloudUrl, source: 'saved', saved: true, enabled: saved.enabled === true }
+  }
+  if (typeof env?.QUICKFORGE_CLOUD_URL === 'string' && env.QUICKFORGE_CLOUD_URL.trim()) {
+    return { value: env.QUICKFORGE_CLOUD_URL, source: 'env', saved: false, enabled: false }
+  }
+  return { value: DEFAULT_CLOUD_URL, source: 'default', saved: false, enabled: false }
+}
+
+export async function readCloudServiceConfig({ readSettings = readStore, env = process.env, strict = true } = {}) {
+  const settings = await readSettings('settings')
+  const candidate = candidateFrom(settings, env)
+  try {
+    const baseUrl = parseCloudBaseUrl(candidate.value)
+    return {
+      schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+      serviceType: CLOUD_SERVICE_TYPE,
+      enabled: candidate.enabled,
+      cloudUrl: baseUrl.href,
+      baseUrl,
+      source: candidate.source,
+      saved: candidate.saved,
+      valid: true,
+    }
+  } catch (error) {
+    if (strict) throw error
+    return {
+      schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+      serviceType: CLOUD_SERVICE_TYPE,
+      enabled: candidate.enabled,
+      cloudUrl: String(candidate.value || '').trim(),
+      source: candidate.source,
+      saved: candidate.saved,
+      valid: false,
+      configurationError: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export async function saveCloudServiceConfig({ cloudUrl, enabled }, { updateSettings = atomicUpdate } = {}) {
+  const baseUrl = parseCloudBaseUrl(cloudUrl)
+  const record = {
+    schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+    serviceType: CLOUD_SERVICE_TYPE,
+    enabled: enabled === true,
+    cloudUrl: baseUrl.href,
+  }
+  await updateSettings('settings', (settings) => ({
+    ...settings,
+    [CLOUD_SERVICE_SETTINGS_KEY]: record,
+  }))
+  return record
+}
+
+export function publicCloudServiceConfig(config) {
+  return {
+    schemaVersion: CLOUD_SERVICE_SCHEMA_VERSION,
+    serviceType: CLOUD_SERVICE_TYPE,
+    enabled: config.enabled === true,
+    cloudUrl: config.cloudUrl,
+    source: config.source,
+    saved: config.saved,
+    valid: config.valid,
+    configurationError: config.configurationError,
+  }
+}

package/server/index.mjs

@@ -17,6 +17,7 @@ import { handleToolApi, handleGetTools } from './routes/tools.mjs'
 import { handleInstructionsApi } from './routes/instructions.mjs'
 import { handleMemoryApi } from './routes/memory.mjs'
 import { handleSkillsApi } from './routes/skills.mjs'
+import { ensureDefaultGlobalSkills } from './skills.mjs'
 import { handleAgentApi } from './routes/agent.mjs'
 import { handleAgentProfilesApi } from './routes/agent-profiles.mjs'
 import { handleScheduledTasksApi, startScheduledTaskRunner, stopScheduledTaskRunner } from './routes/scheduled-tasks.mjs'
@@ -33,6 +34,9 @@ import { handleWorkspaceApi, handleGitApi } from './routes/workspace.mjs'
 import { handleTerminalApi, handleTerminalUpgrade } from './routes/terminal.mjs'
 import { handleChannelsApi } from './routes/channels.mjs'
 import { handleModelsApi } from './routes/models.mjs'
+import { handleCloudApi } from './routes/cloud.mjs'
+import { readCloudServiceConfig } from './cloud/service-config.mjs'
+import { startQfAgent, stopQfAgent, getQfAgentStatus } from './cloud/qf-agent-process.mjs'
 import { serveStatic } from './routes/static.mjs'
 import { logger, flushLogger } from './utils/logger.mjs'
 import { getPackageInfo, checkForUpdates, checkDesktopRelease } from './utils/package-update.mjs'
@@ -45,6 +49,7 @@ import { initializeChannels, shutdownChannels } from './channels/registry.mjs'
 import { shutdownMcpConnections } from './mcp/registry.mjs'
 import { shutdownTerminalSessions } from './terminal/terminal-manager.mjs'
 import { createNodeProcessEnv } from './utils/process-env.mjs'
+import { isAuthenticatedAppClient } from './access-policy.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -65,6 +70,10 @@ const port = Number(process.env.QUICKFORGE_PORT || (isDev ? 32176 : 5176))
 const vitePort = Number(process.env.QUICKFORGE_VITE_PORT || 5176)
 let restartInProgress = false
 let updateInProgress = false
+let shutdownPromise = null
+let shutdownStarted = false
+let qfAgentStartPromise = null
+let boundServerPort = null
 
 setDefaultWorkspaceRoot(process.env.QUICKFORGE_WORKSPACE_DIR || path.join(dataDir, 'workspace'))
 
@@ -72,11 +81,12 @@ function getRestartSupport() {
   return { supported: true, reason: null }
 }
 
-async function getSystemStatus({ isLocalRequest = true } = {}) {
+async function getSystemStatus({ isLocalRequest = true, remoteAuthorized = false } = {}) {
   const config = await readProjectConfig()
   const restartSupport = getRestartSupport()
   const packageInfo = await getPackageInfo(projectRoot)
-  const restartSupported = isLocalRequest && restartSupport.supported
+  const restartAllowed = isAuthenticatedAppClient({ isLocalRequest, remoteAuthorized })
+  const restartSupported = restartAllowed && restartSupport.supported
   return {
     ok: true,
     mode: isDev ? 'development' : 'production',
@@ -92,7 +102,7 @@ async function getSystemStatus({ isLocalRequest = true } = {}) {
       terminal: isLocalRequest,
     },
     restartSupported,
-    restartUnsupportedReason: isLocalRequest ? restartSupport.reason : 'Restart is only allowed from this computer',
+    restartUnsupportedReason: restartAllowed ? restartSupport.reason : 'Restart requires an authenticated client',
     dataDir,
     configDir,
     storageDir,
@@ -149,11 +159,9 @@ function closeHttpServer() {
   })
 }
 
-async function performRestart() {
-  logger.info('Restart requested from settings UI.')
-  const supervisorPid = await spawnRestartSupervisor()
-  logger.info(`Restart supervisor started (PID ${supervisorPid}).`)
-
+async function shutdownRuntime() {
+  shutdownStarted = true
+  await stopQfAgent()
   stopScheduledTaskRunner()
   stopAutoArchiveRunner()
   stopVite()
@@ -162,6 +170,19 @@ async function performRestart() {
   await shutdownChannels()
   shutdownTerminalSessions()
   await closeHttpServer()
+}
+
+export function stopQuickForgeServer() {
+  if (!shutdownPromise) shutdownPromise = shutdownRuntime()
+  return shutdownPromise
+}
+
+async function performRestart() {
+  logger.info('Restart requested from settings UI.')
+  const supervisorPid = await spawnRestartSupervisor()
+  logger.info(`Restart supervisor started (PID ${supervisorPid}).`)
+
+  await stopQuickForgeServer()
   process.exit(0)
 }
 
@@ -228,14 +249,7 @@ function spawnUpdateSupervisor(update) {
 
 async function shutdownForUpdate() {
   logger.info('Shutting down QuickForge for external updater.')
-  stopScheduledTaskRunner()
-  stopAutoArchiveRunner()
-  stopVite()
-  await shutdownAgentManager()
-  await shutdownMcpConnections()
-  await shutdownChannels()
-  shutdownTerminalSessions()
-  await closeHttpServer()
+  await stopQuickForgeServer()
   flushLogger()
   process.exit(0)
 }
@@ -282,6 +296,22 @@ async function updateQuickForge() {
   }
 }
 
+async function applyCloudServiceConfig(cloudConfig, { urlChanged = false } = {}) {
+  if (shutdownStarted) return null
+  if (!cloudConfig.enabled || !cloudConfig.valid) {
+    if (!cloudConfig.valid) logger.warn(`QuickForge remote agent was not started: ${cloudConfig.configurationError || 'invalid Cloud configuration'}`)
+    return stopQfAgent({ disabled: true })
+  }
+  if (!boundServerPort) return null
+  const agentStatus = getQfAgentStatus()
+  if (urlChanged || agentStatus.status === 'disabled' || agentStatus.enabled === false) await stopQfAgent()
+  return startQfAgent({
+    serverUrl: `http://127.0.0.1:${boundServerPort}/`,
+    ownerPid: process.pid,
+    cloudUrl: cloudConfig.cloudUrl,
+  })
+}
+
 // --- Route dispatching ---
 async function handleApi(req, res, url, requestContext = {}) {
   const pathname = url.pathname
@@ -289,12 +319,12 @@ async function handleApi(req, res, url, requestContext = {}) {
 
   // Conversation share routes (management + public LAN access)
   if (pathname === '/api/shares' || pathname.startsWith('/api/shares/')) {
-    await handleSharesApi(req, res, url, { port })
+    await handleSharesApi(req, res, url, { ...requestContext, port })
     return
   }
 
   if (pathname.startsWith('/api/shared/')) {
-    await handleSharedConversationApi(req, res, url)
+    await handleSharedConversationApi(req, res, url, requestContext)
     return
   }
 
@@ -336,13 +366,24 @@ async function handleApi(req, res, url, requestContext = {}) {
 
   // Agent profiles
   if (pathname === '/api/agent-profiles' || pathname.startsWith('/api/agent-profiles/')) {
-    await handleAgentProfilesApi(req, res, url)
+    await handleAgentProfilesApi(req, res, url, requestContext)
+    return
+  }
+
+  // QuickForge Cloud account and managed models (local or authenticated Tailscale requests).
+  if (pathname === '/api/cloud' || pathname.startsWith('/api/cloud/')) {
+    await handleCloudApi(req, res, url, {
+      isLocalRequest: requestContext.isLocalRequest === true,
+      remoteAddress: requestContext.remoteAddress,
+      remoteAuthorized: requestContext.remoteAuthorized === true,
+      onCloudServiceConfigChanged: applyCloudServiceConfig,
+    })
     return
   }
 
   // Custom model management (connection test)
-  if (pathname === '/api/models/test-connection') {
-    await handleModelsApi(req, res, url)
+  if (pathname === '/api/models/catalog' || pathname === '/api/models/test-connection') {
+    await handleModelsApi(req, res, url, requestContext)
     return
   }
 
@@ -387,7 +428,7 @@ async function handleApi(req, res, url, requestContext = {}) {
   }
 
   if (pathname.startsWith('/api/git/')) {
-    await handleGitApi(req, res, url)
+    await handleGitApi(req, res, url, requestContext)
     return
   }
 
@@ -411,19 +452,19 @@ async function handleApi(req, res, url, requestContext = {}) {
 
   // Agent routes
   if (parts[0] === 'api' && parts[1] === 'agents') {
-    await handleAgentApi(req, res, url)
+    await handleAgentApi(req, res, url, requestContext)
     return
   }
 
   // Scheduled task routes
   if (pathname === '/api/scheduled-tasks' || pathname.startsWith('/api/scheduled-tasks/')) {
-    await handleScheduledTasksApi(req, res, url)
+    await handleScheduledTasksApi(req, res, url, requestContext)
     return
   }
 
   // Backup / import-export routes
   if (pathname === '/api/backup/export' || pathname === '/api/backup/import' || pathname === '/api/backup/inspect' || pathname === '/api/backup/inspect-file') {
-    await handleBackupApi(req, res, url)
+    await handleBackupApi(req, res, url, requestContext)
     return
   }
 
@@ -437,6 +478,7 @@ async function handleApi(req, res, url, requestContext = {}) {
       checkDesktopRelease: () => checkDesktopRelease(projectRoot),
       updateQuickForge,
       isLocalRequest: requestContext.isLocalRequest === true,
+      remoteAuthorized: requestContext.remoteAuthorized === true,
       getTerminalShellSetting: readTerminalShellSetting,
       updateTerminalShellSetting,
       getTerminalShellConfig: readTerminalShellConfig,
@@ -461,7 +503,7 @@ async function handleApi(req, res, url, requestContext = {}) {
 
   // Storage routes (catch-all)
   if (parts[0] === 'api' && parts[1] === 'storage') {
-    await handleStorageApi(req, res, url)
+    await handleStorageApi(req, res, url, requestContext)
     return
   }
 
@@ -532,6 +574,24 @@ function isAllowedHostHeader(value) {
   return allowedHosts.has(parsed.hostname) && hostPort === expectedPort
 }
 
+const trustedTunnelSocket = Symbol('trustedTunnelSocket')
+
+function isTunnelClientRequest(req) {
+  if (
+    isLoopbackAddress(req.socket.remoteAddress)
+    && req.headers['x-quickforge-tunnel'] === '1'
+    && req.headers.host === '127.0.0.1:18080'
+  ) {
+    req.socket[trustedTunnelSocket] = true
+  }
+  return req.socket[trustedTunnelSocket] === true
+}
+
+function isAllowedRequestHost(req, isTunnelClient) {
+  return isAllowedHostHeader(req.headers.host)
+    || (isTunnelClient && req.headers.host === '127.0.0.1:18080')
+}
+
 function isLanAccessBootstrapPath(pathname) {
   return pathname === '/api/health'
     || pathname === '/api/lan-access/status'
@@ -571,7 +631,11 @@ const server = createServer(async (req, res) => {
     reqLogger.info(`${req.method} ${req.url} ${res.statusCode}`, { method: req.method, url: req.url, status: res.statusCode, durationMs })
   })
 
-  if (!isAllowedHostHeader(req.headers.host)) {
+  const remoteAddress = req.socket.remoteAddress
+  // 云远程访问（RemoteTunnel）：agent 与 qf 同机时流量经 127.0.0.1 回环进入并携带
+  // X-QuickForge-Tunnel: 1。仅该可信隧道允许手机本地入口 127.0.0.1:18080 作为 Host。
+  const isTunnelClient = isTunnelClientRequest(req)
+  if (!isAllowedRequestHost(req, isTunnelClient)) {
     res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' })
     res.end(JSON.stringify({ error: 'Forbidden host' }))
     return
@@ -593,11 +657,11 @@ const server = createServer(async (req, res) => {
   }
   try {
     const url = new URL(req.url || '/', `http://${req.headers.host || `${host}:${port}`}`)
-    const remoteAddress = req.socket.remoteAddress
-    const isRemoteRequest = !isLoopbackAddress(remoteAddress)
-    const remoteAuthorized = isRemoteRequest ? await isAuthorizedRemoteRequest(req) : true
+    // 隧道请求视为“已认证远程客户端”：认证通过，但本地能力按远程请求裁剪。
+    const isRemoteRequest = isTunnelClient || !isLoopbackAddress(remoteAddress)
+    const remoteAuthorized = isRemoteRequest ? (isTunnelClient ? true : await isAuthorizedRemoteRequest(req)) : true
 
-    if (isRemoteRequest && shareLanEnabled && !remoteAuthorized && !isLanAccessBootstrapPath(url.pathname) && !isSharePath(url.pathname) && !isStaticAssetPath(url.pathname)) {
+    if (isRemoteRequest && !remoteAuthorized && !isLanAccessBootstrapPath(url.pathname) && !isSharePath(url.pathname) && !isStaticAssetPath(url.pathname)) {
       if (url.pathname.startsWith('/api/')) {
         sendLanAuthRequired(res)
       } else {
@@ -609,7 +673,6 @@ const server = createServer(async (req, res) => {
     if (
       url.pathname.startsWith('/api/') &&
       isRemoteRequest &&
-      shareLanEnabled &&
       !remoteAuthorized &&
       !(url.pathname.startsWith('/api/shared/') || url.pathname === '/api/health' || url.pathname.startsWith('/api/lan-access/'))
     ) {
@@ -619,7 +682,12 @@ const server = createServer(async (req, res) => {
     }
 
     if (url.pathname.startsWith('/api/')) {
-      await handleApi(req, res, url, { isLocalRequest: !isRemoteRequest })
+      await handleApi(req, res, url, {
+        isLocalRequest: !isRemoteRequest,
+        remoteAddress,
+        remoteAuthorized,
+        tunnelClient: isTunnelClient,
+      })
       return
     }
 
@@ -633,7 +701,7 @@ const server = createServer(async (req, res) => {
       return
     }
 
-    if (isRemoteRequest && shareLanEnabled && !remoteAuthorized) {
+    if (isRemoteRequest && !remoteAuthorized) {
       res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' })
       res.end(JSON.stringify({ error: 'Remote access is limited to shared conversation links.' }))
       return
@@ -661,7 +729,8 @@ function writeAndDestroySocket(socket, statusLine) {
 }
 
 server.on('upgrade', (req, socket, head) => {
-  if (!isAllowedHostHeader(req.headers.host)) {
+  const isTunnelClient = isTunnelClientRequest(req)
+  if (!isAllowedRequestHost(req, isTunnelClient)) {
     writeAndDestroySocket(socket, 'HTTP/1.1 403 Forbidden')
     return
   }
@@ -670,7 +739,8 @@ server.on('upgrade', (req, socket, head) => {
     const url = new URL(req.url || '/', `http://${req.headers.host || `${host}:${port}`}`)
     if (url.pathname.startsWith('/api/terminal/sessions/')) {
       handleTerminalUpgrade(req, socket, head, url, {
-        isLocalRequest: isLoopbackAddress(req.socket.remoteAddress),
+        // 隧道流量同样是远程客户端：终端 WebSocket 保持禁止。
+        isLocalRequest: isLoopbackAddress(req.socket.remoteAddress) && !isTunnelClient,
       })
       return
     }
@@ -681,6 +751,7 @@ server.on('upgrade', (req, socket, head) => {
 })
 
 await ensureStorage()
+await ensureDefaultGlobalSkills()
 await initializeNetworkProxy()
 installAiHttpLogger()
 initializeChannels({
@@ -708,35 +779,40 @@ server.on('error', (error) => {
 })
 
 server.listen(port, host, () => {
-  logger.info(`QuickForge local API: http://${host}:${port}`)
+  const address = server.address()
+  const boundPort = typeof address === 'object' && address ? address.port : port
+  boundServerPort = boundPort
+  logger.info(`QuickForge local API: http://${host}:${boundPort}`)
   if (shareLanEnabled) {
-    const lanUrls = getLanUrls(port)
-    logger.info(`QuickForge LAN sharing is enabled. Share pages are available at: ${lanUrls.length ? lanUrls.join(', ') : `http://<your-lan-ip>:${port}`}`)
+    const lanUrls = getLanUrls(boundPort)
+    logger.info(`QuickForge LAN sharing is enabled. Share pages are available at: ${lanUrls.length ? lanUrls.join(', ') : `http://<your-lan-ip>:${boundPort}`}`)
     logger.info('Remote non-share API routes are restricted while QUICKFORGE_SHARE_LAN=1.')
   }
   logger.info(`QuickForge data dir: ${dataDir}`)
   logger.info(`QuickForge project: ${getWorkspaceRoot()}`)
 
+  const pending = readCloudServiceConfig({ strict: false }).then((cloudConfig) => applyCloudServiceConfig(cloudConfig)).catch((error) => {
+    if (!shutdownStarted) logger.warn(`QuickForge remote agent failed to start: ${error?.message || error}`)
+    return null
+  }).finally(() => {
+    if (qfAgentStartPromise === pending) qfAgentStartPromise = null
+  })
+  qfAgentStartPromise = pending
+
   if (isDev) {
     startVite()
     setTimeout(() => openBrowser(`http://localhost:${vitePort}`), 1000)
   } else if (shareLanEnabled) {
-    openBrowser(`http://localhost:${port}`)
+    openBrowser(`http://localhost:${boundPort}`)
   } else {
-    openBrowser(`http://localhost:${port}`)
+    openBrowser(`http://localhost:${boundPort}`)
   }
 })
 
 // Graceful shutdown
 async function gracefulShutdown(signal) {
   logger.info(`Received ${signal}, shutting down gracefully...`)
-  stopScheduledTaskRunner()
-  stopAutoArchiveRunner()
-  stopVite()
-  await shutdownAgentManager()
-  await shutdownMcpConnections()
-  await shutdownChannels()
-  shutdownTerminalSessions()
+  await stopQuickForgeServer()
   flushLogger()
   process.exit(0)
 }

package/server/mcp/registry.mjs

@@ -215,22 +215,21 @@ async function refreshConnections() {
     }
   }
 
-  for (const config of enabled.values()) {
+  const refreshed = await Promise.all([...enabled.values()].map(async (config) => {
     const existing = connections.get(config.name)
     if (existing) {
       if (existing.status === 'error' && Date.now() - (existing.lastAttemptAt || 0) >= RETRY_ERROR_AFTER_MS) {
         connections.delete(config.name)
         await closeConnection(existing)
       } else {
-        continue
+        return [config.name, existing]
       }
     }
     try {
-      const connection = await connectServer(config)
-      connections.set(config.name, connection)
+      return [config.name, await connectServer(config)]
     } catch (error) {
       logger.error(`Failed to connect MCP server ${config.name}:`, error)
-      connections.set(config.name, {
+      return [config.name, {
         config,
         client: null,
         transport: null,
@@ -240,10 +239,12 @@ async function refreshConnections() {
         connectedAt: null,
         stderr: '',
         lastAttemptAt: Date.now(),
-      })
+      }]
     }
-  }
+  }))
 
+  connections.clear()
+  for (const [name, connection] of refreshed) connections.set(name, connection)
   return connections
 }
 

package/server/message-converters.mjs

@@ -21,30 +21,51 @@ export function omitDetailsForLlm(message) {
  * Handles "user-with-attachments" → "user" with multi-modal content blocks.
  * Without this the default pi-agent-core convertToLlm silently drops
  * user-with-attachments messages, so the LLM never sees attachments.
+ *
+ * Also guards against orphaned toolResult messages (a tool result without a
+ * preceding assistant tool_call): OpenAI-compatible APIs reject such sequences
+ * with 400 "Messages with role 'tool' must be a response to a preceding
+ * message with 'tool_calls'". Assistant messages that pi-ai would skip
+ * (stopReason error/aborted) are not counted as valid tool_call ancestors,
+ * matching the upstream skip logic so their results are dropped too.
  */
 export function serverConvertToLlm(messages) {
-  return messages
-    .filter(m => m.role !== 'artifact')
-    .map(m => {
-      if (m.role === 'user-with-attachments') {
-        const textContent = typeof m.content === 'string'
-          ? [{ type: 'text', text: m.content }]
-          : [...m.content]
-        if (Array.isArray(m.attachments)) {
-          for (const att of m.attachments) {
-            if (att.type === 'image' && att.content) {
-              textContent.push({ type: 'image', data: att.content, mimeType: att.mimeType })
-            } else if (att.type === 'document' && att.extractedText) {
-              textContent.push({ type: 'text', text: `\n\n[Document: ${att.fileName}]\n${att.extractedText}` })
-            }
+  const pendingToolCallIds = new Set()
+  const converted = []
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue
+    if (m.role === 'artifact') continue
+    if (m.role === 'user-with-attachments') {
+      const textContent = typeof m.content === 'string'
+        ? [{ type: 'text', text: m.content }]
+        : [...m.content]
+      if (Array.isArray(m.attachments)) {
+        for (const att of m.attachments) {
+          if (att.type === 'image' && att.content) {
+            textContent.push({ type: 'image', data: att.content, mimeType: att.mimeType })
+          } else if (att.type === 'document' && att.extractedText) {
+            textContent.push({ type: 'text', text: `\n\n[Document: ${att.fileName}]\n${att.extractedText}` })
           }
         }
-        return omitDetailsForLlm({ ...m, role: 'user', content: textContent })
       }
-      if (m.role === 'user' || m.role === 'assistant' || m.role === 'toolResult') return omitDetailsForLlm(m)
-      return null
-    })
-    .filter(Boolean)
+      converted.push(omitDetailsForLlm({ ...m, role: 'user', content: textContent }))
+    } else if (m.role === 'user') {
+      converted.push(omitDetailsForLlm(m))
+    } else if (m.role === 'assistant') {
+      if (m.stopReason !== 'error' && m.stopReason !== 'aborted' && Array.isArray(m.content)) {
+        for (const block of m.content) {
+          if (block?.type === 'toolCall' && block.id) pendingToolCallIds.add(block.id)
+        }
+      }
+      converted.push(omitDetailsForLlm(m))
+    } else if (m.role === 'toolResult') {
+      // 孤儿 toolResult（无前导 assistant tool_calls）直接丢弃，避免上游 400
+      if (!m.toolCallId || !pendingToolCallIds.has(m.toolCallId)) continue
+      pendingToolCallIds.delete(m.toolCallId)
+      converted.push(omitDetailsForLlm(m))
+    }
+  }
+  return converted
 }
 
 /**