@shawnstack/quickforge 1.7.3 → 1.7.5

package/server/index.mjs

@@ -5,7 +5,7 @@ import path from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import { sendJson, sendError } from './utils/response.mjs'
-import { openBrowser } from './utils/platform.mjs'
+import { openBrowser, openPathInFileManager } from './utils/platform.mjs'
 import { ensureStorage, dataDir, configDir, storageDir, cacheDir, logsDir } from './storage.mjs'
 import { getNetworkProxyConfig, initializeNetworkProxy, refreshSystemProxy, updateNetworkProxyConfig } from './network-proxy.mjs'
 import { setDefaultWorkspaceRoot, initializeActiveProject, readProjectConfig, getActiveProject, readTerminalShellSetting, updateTerminalShellSetting, readTerminalShellConfig, updateTerminalShellConfig } from './project-config.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,7 @@ 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 { serveStatic } from './routes/static.mjs'
 import { logger, flushLogger } from './utils/logger.mjs'
 import { getPackageInfo, checkForUpdates, checkDesktopRelease } from './utils/package-update.mjs'
@@ -44,6 +46,7 @@ import { shutdown as shutdownAgentManager, resetStaleTaskStatuses } from './agen
 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'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -71,10 +74,11 @@ function getRestartSupport() {
   return { supported: true, reason: null }
 }
 
-async function getSystemStatus() {
+async function getSystemStatus({ isLocalRequest = true } = {}) {
   const config = await readProjectConfig()
   const restartSupport = getRestartSupport()
   const packageInfo = await getPackageInfo(projectRoot)
+  const restartSupported = isLocalRequest && restartSupport.supported
   return {
     ok: true,
     mode: isDev ? 'development' : 'production',
@@ -83,8 +87,14 @@ async function getSystemStatus() {
     startedAt,
     version: packageInfo.version,
     package: packageInfo,
-    restartSupported: restartSupport.supported,
-    restartUnsupportedReason: restartSupport.reason,
+    isLocalRequest,
+    capabilities: {
+      restart: restartSupported,
+      openLocalApps: isLocalRequest,
+      terminal: isLocalRequest,
+    },
+    restartSupported,
+    restartUnsupportedReason: isLocalRequest ? restartSupport.reason : 'Restart is only allowed from this computer',
     dataDir,
     configDir,
     storageDir,
@@ -113,10 +123,9 @@ function spawnRestartSupervisor() {
       stdio: 'ignore',
       windowsHide: true,
       shell: false,
-      env: {
-        ...process.env,
+      env: createNodeProcessEnv(process.env, {
         QUICKFORGE_NO_OPEN: '1',
-      },
+      }),
     })
 
     child.once('error', reject)
@@ -206,10 +215,9 @@ function spawnUpdateSupervisor(update) {
       stdio: 'ignore',
       windowsHide: true,
       shell: false,
-      env: {
-        ...process.env,
+      env: createNodeProcessEnv(process.env, {
         QUICKFORGE_NO_OPEN: '1',
-      },
+      }),
     })
 
     child.once('error', reject)
@@ -277,18 +285,18 @@ async function updateQuickForge() {
 }
 
 // --- Route dispatching ---
-async function handleApi(req, res, url) {
+async function handleApi(req, res, url, requestContext = {}) {
   const pathname = url.pathname
   const parts = pathname.split('/').filter(Boolean)
 
   // 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
   }
 
@@ -297,22 +305,22 @@ async function handleApi(req, res, url) {
     return
   }
 
-  if (pathname === '/api/lan-access/status' || pathname === '/api/lan-access/settings' || pathname === '/api/lan-access/unlock' || pathname === '/api/lan-access/logout' || pathname === '/api/lan-access/revoke-all') {
+  if (pathname.startsWith('/api/lan-access/')) {
     await handleLanAccessApi(req, res, url, {
       port,
-      isLocalRequest: isLoopbackAddress(req.socket.remoteAddress),
+      isLocalRequest: requestContext.isLocalRequest === true,
     })
     return
   }
 
   // Health check
   if (req.method === 'GET' && pathname === '/api/health') {
-    sendJson(res, 200, await getSystemStatus())
+    sendJson(res, 200, await getSystemStatus(requestContext))
     return
   }
 
   if (req.method === 'GET' && pathname === '/api/project/commands') {
-    await handleProjectApi(req, res, url)
+    await handleProjectApi(req, res, url, requestContext)
     return
   }
 
@@ -330,13 +338,23 @@ async function handleApi(req, res, url) {
 
   // 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,
+    })
     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
   }
 
@@ -355,7 +373,9 @@ async function handleApi(req, res, url) {
   // Channels
   if (pathname === '/api/channels' || pathname.startsWith('/api/channels/')) {
     await handleChannelsApi(req, res, url, {
-      isLocalRequest: isLoopbackAddress(req.socket.remoteAddress),
+      isLocalRequest: requestContext.isLocalRequest === true,
+      logsDir,
+      openPathInFileManager,
     })
     return
   }
@@ -368,18 +388,18 @@ async function handleApi(req, res, url) {
 
   // Project routes
   if (pathname === '/api/project' || pathname.startsWith('/api/project/')) {
-    await handleProjectApi(req, res, url)
+    await handleProjectApi(req, res, url, requestContext)
     return
   }
 
   // Project workspace inspector routes
   if (pathname === '/api/workspace/tree' || pathname === '/api/workspace/file' || pathname === '/api/workspace/resolve-path' || pathname === '/api/workspace/open-external' || pathname.startsWith('/api/workspace/preview/')) {
-    await handleWorkspaceApi(req, res, url)
+    await handleWorkspaceApi(req, res, url, requestContext)
     return
   }
 
   if (pathname.startsWith('/api/git/')) {
-    await handleGitApi(req, res, url)
+    await handleGitApi(req, res, url, requestContext)
     return
   }
 
@@ -403,32 +423,32 @@ async function handleApi(req, res, url) {
 
   // 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
   }
 
   // System routes
   if (pathname === '/api/system/status' || pathname === '/api/system/restart' || pathname === '/api/system/network' || pathname === '/api/system/network-proxy' || pathname === '/api/system/network-proxy/refresh' || pathname === '/api/system/terminal-shell' || pathname === '/api/system/about' || pathname === '/api/system/update/check' || pathname === '/api/system/update/desktop' || pathname === '/api/system/update') {
     await handleSystemApi(req, res, url, {
-      getSystemStatus,
+      getSystemStatus: () => getSystemStatus(requestContext),
       requestRestart,
       getPackageInfo: () => getPackageInfo(projectRoot),
       checkForUpdates: () => checkForUpdates(projectRoot),
       checkDesktopRelease: () => checkDesktopRelease(projectRoot),
       updateQuickForge,
-      isLocalRequest: isLoopbackAddress(req.socket.remoteAddress),
+      isLocalRequest: requestContext.isLocalRequest === true,
       getTerminalShellSetting: readTerminalShellSetting,
       updateTerminalShellSetting,
       getTerminalShellConfig: readTerminalShellConfig,
@@ -446,14 +466,14 @@ async function handleApi(req, res, url) {
   // Terminal routes (local-only; real shell access)
   if (pathname === '/api/terminal/capabilities' || pathname === '/api/terminal/sessions' || pathname.startsWith('/api/terminal/sessions/')) {
     await handleTerminalApi(req, res, url, {
-      isLocalRequest: isLoopbackAddress(req.socket.remoteAddress),
+      isLocalRequest: requestContext.isLocalRequest === true,
     })
     return
   }
 
   // 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 +552,7 @@ function isLanAccessBootstrapPath(pathname) {
 
 function isStaticAssetPath(pathname) {
   return pathname.startsWith('/assets/')
+    || pathname.startsWith('/downloads/')
     || pathname === '/favicon.svg'
     || pathname === '/vite.svg'
     || pathname === '/manifest.webmanifest'
@@ -610,7 +631,11 @@ const server = createServer(async (req, res) => {
     }
 
     if (url.pathname.startsWith('/api/')) {
-      await handleApi(req, res, url)
+      await handleApi(req, res, url, {
+        isLocalRequest: !isRemoteRequest,
+        remoteAddress,
+        remoteAuthorized,
+      })
       return
     }
 
@@ -672,9 +697,14 @@ server.on('upgrade', (req, socket, head) => {
 })
 
 await ensureStorage()
+await ensureDefaultGlobalSkills()
 await initializeNetworkProxy()
 installAiHttpLogger()
-initializeChannels({ projectRoot })
+initializeChannels({
+  projectRoot,
+  channelEventsUrl: `http://127.0.0.1:${port}/api/channels/events`,
+  logsDir,
+})
 await resetStaleTaskStatuses()
 await initializeActiveProject()
 setActiveWorkspaceRootForFilesystem(getWorkspaceRoot())

package/server/lan-access-store.mjs

@@ -80,13 +80,41 @@ async function writeLanAccessFile(config) {
   await fs.writeFile(LAN_ACCESS_FILE, `${JSON.stringify(normalizeConfig(config), null, 2)}\n`, 'utf8')
 }
 
+function normalizeText(value, maxLength) {
+  if (typeof value !== 'string') return undefined
+  const text = value.trim()
+  return text ? text.slice(0, maxLength) : undefined
+}
+
+function normalizeRemoteAddress(value) {
+  const address = normalizeText(value, 128)
+  return address?.startsWith('::ffff:') ? address.slice(7) : address
+}
+
+function tokenRecordId(tokenRecord) {
+  const id = normalizeText(tokenRecord?.id, 128)
+  return id || `legacy_${sha256Base64Url(tokenRecord?.tokenHash || '').slice(0, 24)}`
+}
+
+function publicTokenRecord(tokenRecord) {
+  return {
+    id: tokenRecordId(tokenRecord),
+    address: normalizeRemoteAddress(tokenRecord.remoteAddress),
+    userAgent: normalizeText(tokenRecord.userAgent, 300),
+    issuedAt: tokenRecord.issuedAt,
+    expiresAt: tokenRecord.expiresAt,
+  }
+}
+
 function publicStatus(config) {
+  const activeTokens = pruneTokens(config.tokens)
   return {
     enabled: Boolean(config.enabled),
     hasPassword: Boolean(config.passwordHash),
     sessionTtlHours: config.sessionTtlHours,
     authVersion: config.authVersion || 1,
-    activeTokenCount: pruneTokens(config.tokens).length,
+    activeTokenCount: activeTokens.length,
+    activeDevices: activeTokens.map(publicTokenRecord),
     updatedAt: config.updatedAt,
   }
 }
@@ -98,6 +126,12 @@ function pruneTokens(tokens, now = Date.now()) {
       if (!tokenRecord.expiresAt) return true
       return Date.parse(tokenRecord.expiresAt) > now
     })
+    .map((tokenRecord) => ({
+      ...tokenRecord,
+      id: tokenRecordId(tokenRecord),
+      remoteAddress: normalizeRemoteAddress(tokenRecord.remoteAddress),
+      userAgent: normalizeText(tokenRecord.userAgent, 300),
+    }))
     .slice(-LAN_TOKEN_MAX_COUNT)
 }
 
@@ -162,11 +196,58 @@ export async function revokeLanAccessTokens() {
   })
 }
 
+export async function revokeLanAccessTokenById(id) {
+  const normalizedId = normalizeText(id, 128)
+  if (!normalizedId) {
+    const error = new Error('LAN access session id is required.')
+    error.statusCode = 400
+    throw error
+  }
+  return enqueueWrite(writeQueueName, async () => {
+    const current = await readLanAccessFile()
+    const tokens = pruneTokens(current.tokens)
+    const nextTokens = tokens.filter((tokenRecord) => tokenRecordId(tokenRecord) !== normalizedId)
+    if (nextTokens.length === tokens.length) {
+      const error = new Error('LAN access session not found.')
+      error.statusCode = 404
+      throw error
+    }
+    const next = normalizeConfig({
+      ...current,
+      tokens: nextTokens,
+      updatedAt: new Date().toISOString(),
+    })
+    await writeLanAccessFile(next)
+    return publicStatus(next)
+  })
+}
+
+export async function revokeLanAccessToken(token) {
+  if (!token || typeof token !== 'string') return false
+  const [versionText, secret] = token.split('.')
+  if (!secret) return false
+  const actualHash = sha256Base64Url(secret)
+  return enqueueWrite(writeQueueName, async () => {
+    const current = await readLanAccessFile()
+    if (Number(versionText) !== (current.authVersion || 1)) return false
+    const tokens = pruneTokens(current.tokens)
+    const nextTokens = tokens.filter((tokenRecord) => !safeHashEqual(tokenRecord.tokenHash, actualHash))
+    if (nextTokens.length === tokens.length) return false
+    const next = normalizeConfig({
+      ...current,
+      tokens: nextTokens,
+      updatedAt: new Date().toISOString(),
+    })
+    await writeLanAccessFile(next)
+    return true
+  })
+}
+
 export function lanAccessCookieName() {
   return 'qf_lan_access'
 }
 
-export async function issueLanAccessToken(password) {
+export async function issueLanAccessToken(password, metadata = {}) {
   return enqueueWrite(writeQueueName, async () => {
     const current = await readLanAccessFile()
     if (!current.enabled || !current.passwordHash) {
@@ -185,11 +266,20 @@ export async function issueLanAccessToken(password) {
     const issuedAt = new Date().toISOString()
     const ttlMs = normalizeSessionTtlHours(current.sessionTtlHours) * 60 * 60 * 1000
     const expiresAt = new Date(Date.now() + ttlMs).toISOString()
+    const tokenRecord = {
+      id: createRandomToken(18),
+      tokenHash,
+      issuedAt,
+      expiresAt,
+      authVersion: current.authVersion || 1,
+      remoteAddress: normalizeRemoteAddress(metadata.remoteAddress),
+      userAgent: normalizeText(metadata.userAgent, 300),
+    }
     const next = normalizeConfig({
       ...current,
       tokens: [
         ...pruneTokens(current.tokens),
-        { tokenHash, issuedAt, expiresAt, authVersion: current.authVersion || 1 },
+        tokenRecord,
       ].slice(-LAN_TOKEN_MAX_COUNT),
       updatedAt: issuedAt,
     })

package/server/model-catalog.mjs

@@ -0,0 +1,262 @@
+import { getCloudRuntime } from './cloud/runtime.mjs'
+import { isManagedCloudModel } from './cloud/models.mjs'
+import { readStore } from './storage.mjs'
+import { isTailscaleAddress } from './utils/network.mjs'
+
+export const MODEL_REFERENCE_VERSION = 1
+
+function requestError(message, statusCode = 400, code) {
+  const error = new Error(message)
+  error.statusCode = statusCode
+  if (code) {
+    error.code = code
+    error.errorCode = code
+  }
+  return error
+}
+
+function normalizedBaseUrl(value) {
+  return String(value || '').trim().replace(/\/$/, '')
+}
+
+function isUsableModel(model) {
+  return Boolean(model && typeof model === 'object' && model.id && model.provider && model.api && model.baseUrl)
+}
+
+function sameModel(left, right) {
+  return Boolean(left && right
+    && left.id === right.id
+    && left.provider === right.provider
+    && left.api === right.api
+    && normalizedBaseUrl(left.baseUrl) === normalizedBaseUrl(right.baseUrl))
+}
+
+function publicModel(model, modelRef) {
+  const result = {
+    ...model,
+    quickforgeModelRef: modelRef,
+  }
+  delete result.apiKey
+  delete result.key
+  delete result.headers
+  return result
+}
+
+async function configuredProviders() {
+  const store = await readStore('custom-providers').catch(() => ({}))
+  return Array.isArray(store) ? store : Object.values(store || {})
+}
+
+function configuredEntries(providers) {
+  return providers.flatMap((provider) => {
+    const providerId = String(provider?.id || '').trim()
+    return (Array.isArray(provider?.models) ? provider.models : [])
+      .filter(isUsableModel)
+      .map((model) => ({ provider, providerId, model }))
+  })
+}
+
+export function cloudAllowedForContext(context = {}) {
+  if (context.allowCloud === false) return false
+  if (context.allowCloud === true || context.source === 'acp' || context.source === 'scheduled') return true
+  if (context.isLocalRequest !== false) return true
+  return context.remoteAuthorized === true && isTailscaleAddress(context.remoteAddress)
+}
+
+export function modelReferenceFromSnapshot(model, providers = []) {
+  if (!model || typeof model !== 'object') return null
+  if (isManagedCloudModel(model)) {
+    const catalogId = String(model.quickforgeCatalogId || model.id || '').trim()
+    return catalogId ? { version: MODEL_REFERENCE_VERSION, source: 'cloud', catalogId } : null
+  }
+
+  const matched = configuredEntries(providers).find((entry) => sameModel(entry.model, model))
+  if (matched?.providerId) {
+    return {
+      version: MODEL_REFERENCE_VERSION,
+      source: 'custom',
+      providerId: matched.providerId,
+      modelId: matched.model.id,
+    }
+  }
+
+  if (model.provider && model.id) {
+    return {
+      version: MODEL_REFERENCE_VERSION,
+      source: 'legacy-custom',
+      provider: String(model.provider),
+      modelId: String(model.id),
+      ...(model.api ? { api: String(model.api) } : {}),
+      ...(model.baseUrl ? { baseUrl: String(model.baseUrl) } : {}),
+    }
+  }
+  return null
+}
+
+export function normalizeModelReference(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const source = String(value.source || '').trim()
+  if (source === 'cloud') {
+    const catalogId = String(value.catalogId || value.quickforgeCatalogId || value.modelId || '').trim()
+    return catalogId ? { version: MODEL_REFERENCE_VERSION, source: 'cloud', catalogId } : null
+  }
+  if (source === 'custom') {
+    const providerId = String(value.providerId || '').trim()
+    const modelId = String(value.modelId || value.id || '').trim()
+    return providerId && modelId
+      ? { version: MODEL_REFERENCE_VERSION, source: 'custom', providerId, modelId }
+      : null
+  }
+  if (source === 'legacy-custom') {
+    const provider = String(value.provider || '').trim()
+    const modelId = String(value.modelId || value.id || '').trim()
+    return provider && modelId
+      ? {
+          version: MODEL_REFERENCE_VERSION,
+          source: 'legacy-custom',
+          provider,
+          modelId,
+          ...(value.api ? { api: String(value.api) } : {}),
+          ...(value.baseUrl ? { baseUrl: String(value.baseUrl) } : {}),
+        }
+      : null
+  }
+  return null
+}
+
+async function listCloudModels(context, { refresh = false } = {}) {
+  if (!cloudAllowedForContext(context)) return []
+  try {
+    const runtime = await getCloudRuntime()
+    if (!runtime?.enabled) return []
+    const models = await runtime.models.list(undefined, { refresh })
+    return models.filter((model) => model?.quickforgeCatalogId)
+  } catch {
+    return []
+  }
+}
+
+export async function listModelCatalog({
+  context = {},
+  includeHidden = false,
+  currentModel = null,
+  refreshCloud = false,
+} = {}) {
+  const providers = await configuredProviders()
+  const custom = configuredEntries(providers)
+    .filter(({ model }) => includeHidden || model.quickforgeHidden !== true || sameModel(model, currentModel))
+    .map(({ providerId, model }) => publicModel(model, {
+      version: MODEL_REFERENCE_VERSION,
+      source: 'custom',
+      providerId,
+      modelId: model.id,
+    }))
+  if (currentModel) {
+    const currentIndex = custom.findIndex((model) => sameModel(model, currentModel))
+    if (currentIndex > 0 && custom[currentIndex].quickforgeHidden === true) {
+      custom.unshift(custom.splice(currentIndex, 1)[0])
+    }
+  }
+  const cloud = (await listCloudModels(context, { refresh: refreshCloud }))
+    .map((model) => publicModel(model, {
+      version: MODEL_REFERENCE_VERSION,
+      source: 'cloud',
+      catalogId: model.quickforgeCatalogId,
+    }))
+
+  if (currentModel && ![...custom, ...cloud].some((model) => sameModel(model, currentModel))) {
+    const ref = modelReferenceFromSnapshot(currentModel, providers)
+    if (ref) return [publicModel(currentModel, ref), ...custom, ...cloud]
+  }
+  return [...custom, ...cloud]
+}
+
+async function resolveCloud(ref, context) {
+  if (!cloudAllowedForContext(context)) {
+    throw requestError('QuickForge Cloud is not available from this client.', 403, 'cloud_access_denied')
+  }
+  const runtime = await getCloudRuntime()
+  if (!runtime?.enabled) throw requestError('QuickForge Cloud is not configured.', 503, 'cloud_not_configured')
+  return (await runtime.models.resolve({
+    provider: 'quickforge-cloud',
+    quickforgeModelSource: 'cloud',
+    quickforgeCatalogId: ref.catalogId,
+  })).publicModel
+}
+
+function findCustomByReference(ref, entries) {
+  if (ref.source === 'custom') {
+    return entries.find(({ providerId, model }) => providerId === ref.providerId && model.id === ref.modelId)?.model
+  }
+  if (ref.source === 'legacy-custom') {
+    return entries.find(({ model }) => model.provider === ref.provider
+      && model.id === ref.modelId
+      && (!ref.api || model.api === ref.api)
+      && (!ref.baseUrl || normalizedBaseUrl(model.baseUrl) === normalizedBaseUrl(ref.baseUrl)))?.model
+  }
+  return null
+}
+
+export async function resolveModelBinding(input, {
+  context = {},
+  currentModel = null,
+  allowCurrentHidden = false,
+  forExecution = false,
+  legacySnapshot = null,
+} = {}) {
+  const providers = await configuredProviders()
+  const entries = configuredEntries(providers)
+  const explicitRef = normalizeModelReference(input?.modelRef || input?.quickforgeModelRef || input)
+  const snapshot = input?.model && typeof input.model === 'object'
+    ? input.model
+    : (!explicitRef && input && typeof input === 'object' && input.id ? input : legacySnapshot)
+  const ref = explicitRef || modelReferenceFromSnapshot(snapshot, providers)
+  if (!ref) throw requestError('A valid model reference is required.', 400, 'invalid_model_reference')
+
+  if (ref.source === 'cloud') {
+    const model = await resolveCloud(ref, context)
+    return { model, modelRef: ref }
+  }
+
+  const configured = findCustomByReference(ref, entries)
+  if (configured) {
+    const hidden = configured.quickforgeHidden === true
+    if (hidden && !forExecution && !(allowCurrentHidden && sameModel(configured, currentModel))) {
+      throw requestError('Selected model is not available for new selection.', 400, 'model_not_selectable')
+    }
+    const canonicalRef = modelReferenceFromSnapshot(configured, providers)
+    return { model: configured, modelRef: canonicalRef }
+  }
+
+  throw requestError('Selected model is not configured in QuickForge.', 400, 'model_not_configured')
+}
+
+export async function resolveImplicitModelPreference(value, context = {}) {
+  let stored = value
+  if (typeof stored === 'string') {
+    try { stored = JSON.parse(stored) } catch { stored = null }
+  }
+  const ref = normalizeModelReference(stored?.modelRef || stored?.quickforgeModelRef)
+  const snapshot = stored?.modelSnapshot || stored?.model || (stored?.id ? stored : null)
+  const catalog = await listModelCatalog({ context })
+  if (ref) {
+    const matched = catalog.find((model) => {
+      const candidate = normalizeModelReference(model.quickforgeModelRef)
+      if (!candidate || candidate.source !== ref.source) return false
+      if (ref.source === 'cloud') return candidate.catalogId === ref.catalogId
+      if (ref.source === 'custom') return candidate.providerId === ref.providerId && candidate.modelId === ref.modelId
+      return false
+    })
+    if (matched) return matched
+  }
+  if (snapshot) {
+    const matched = catalog.find((model) => sameModel(model, snapshot))
+    if (matched) return matched
+  }
+  return catalog[0] || null
+}
+
+export async function modelBindingFromModel(model) {
+  const providers = await configuredProviders()
+  return { model, modelRef: modelReferenceFromSnapshot(model, providers) }
+}