@shawnstack/quickforge 1.7.4 → 1.7.6

package/server/agent-profile-files.mjs

@@ -6,7 +6,7 @@ import { logger } from './utils/logger.mjs'
 import { firstOptionalBoolean, firstString, parseFrontmatter, splitDelimitedList } from './frontmatter.mjs'
 import { normalizeAgentProfileThinkingLevel, normalizeCapabilityPolicy, normalizeModelReference, validateAgentProfileTools, validateModelReference } from './agent-profile-schema.mjs'
 
-const DEFAULT_MAX_RUNTIME_MS = 30 * 60 * 1000
+const DEFAULT_MAX_RUNTIME_MS = 60 * 60 * 1000
 const DEFAULT_MAX_TOOL_CALLS = 300
 const nameRegex = /^[a-z][a-z0-9_-]{1,39}$/
 const allowedToolNames = new Set(['read_file', 'grep_files', 'write_file', 'edit_file', 'run_command'])
@@ -66,14 +66,18 @@ function quoteFrontmatter(value) {
 
 function formatModelFrontmatter(model) {
   if (!model || model.mode !== 'fixed') return 'model:\n  mode: inherit'
-  return [
+  const result = [
     'model:',
     '  mode: fixed',
-    `  provider: ${quoteFrontmatter(model.provider)}`,
-    `  modelId: ${quoteFrontmatter(model.modelId)}`,
+    model.source && model.source !== 'legacy-custom' ? `  source: ${quoteFrontmatter(model.source)}` : '',
+    model.providerId ? `  providerId: ${quoteFrontmatter(model.providerId)}` : '',
+    model.catalogId ? `  catalogId: ${quoteFrontmatter(model.catalogId)}` : '',
+    model.provider ? `  provider: ${quoteFrontmatter(model.provider)}` : '',
+    model.modelId ? `  modelId: ${quoteFrontmatter(model.modelId)}` : '',
     model.api ? `  api: ${quoteFrontmatter(model.api)}` : '',
     model.baseUrl ? `  baseUrl: ${quoteFrontmatter(model.baseUrl)}` : '',
   ].filter(Boolean).join('\n')
+  return result
 }
 
 export function userAgentProfileFilePath(name) {

package/server/agent-profile-schema.mjs

@@ -1,3 +1,5 @@
+import { resolveModelBinding } from './model-catalog.mjs'
+
 export const AGENT_PROFILE_TOOL_NAMES = ['read_file', 'grep_files', 'write_file', 'edit_file', 'run_command']
 export const AGENT_PROFILE_MODEL_INHERIT = { mode: 'inherit' }
 export const AGENT_PROFILE_THINKING_LEVELS = ['inherit', 'off', 'low', 'medium', 'high', 'xhigh']
@@ -41,10 +43,6 @@ function normalizeString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined
 }
 
-function sameBaseUrl(a, b) {
-  return String(a || '').trim().replace(/\/$/, '') === String(b || '').trim().replace(/\/$/, '')
-}
-
 function readModelField(value, ...keys) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
   for (const key of keys) {
@@ -90,10 +88,16 @@ export function normalizeModelReference(input, metadata = {}) {
   const flatModelId = normalizeString(metadata['model-id'] ?? metadata.model_id ?? metadata.modelId)
   const flatApi = normalizeString(metadata['model-api'] ?? metadata.modelApi ?? metadata.api)
   const flatBaseUrl = normalizeString(metadata['model-base-url'] ?? metadata.modelBaseUrl ?? metadata.baseUrl)
+  const flatSource = normalizeString(metadata['model-source'] ?? metadata.modelSource)?.toLowerCase()
+  const flatProviderId = normalizeString(metadata['model-provider-id'] ?? metadata.modelProviderId ?? metadata.providerId)
+  const flatCatalogId = normalizeString(metadata['model-catalog-id'] ?? metadata.modelCatalogId ?? metadata.catalogId)
 
-  if (flatMode === 'fixed' || flatProvider || flatModelId) {
+  if (flatMode === 'fixed' || flatSource || flatProvider || flatModelId || flatProviderId || flatCatalogId) {
     return {
       mode: 'fixed',
+      source: flatSource,
+      providerId: flatProviderId,
+      catalogId: flatCatalogId,
       provider: flatProvider,
       modelId: flatModelId,
       api: flatApi,
@@ -123,6 +127,9 @@ export function normalizeModelReference(input, metadata = {}) {
 
   return {
     mode: 'fixed',
+    source: readModelField(modelValue, 'source'),
+    providerId: readModelField(modelValue, 'providerId', 'provider-id', 'provider_id'),
+    catalogId: readModelField(modelValue, 'catalogId', 'catalog-id', 'catalog_id', 'quickforgeCatalogId'),
     provider: readModelField(modelValue, 'provider'),
     modelId: readModelField(modelValue, 'modelId', 'model-id', 'model_id', 'id', 'model'),
     api: readModelField(modelValue, 'api'),
@@ -133,9 +140,19 @@ export function normalizeModelReference(input, metadata = {}) {
 export function validateModelReference(modelRef) {
   const ref = modelRef || AGENT_PROFILE_MODEL_INHERIT
   if (ref.mode !== 'fixed') return { ...AGENT_PROFILE_MODEL_INHERIT }
+  if (ref.source === 'cloud') {
+    const catalogId = ref.catalogId || ref.modelId
+    if (!catalogId) throw requestError('Fixed Cloud agent model requires catalogId')
+    return { mode: 'fixed', source: 'cloud', catalogId }
+  }
+  if (ref.source === 'custom') {
+    if (!ref.providerId || !ref.modelId) throw requestError('Fixed custom agent model requires providerId and modelId')
+    return { mode: 'fixed', source: 'custom', providerId: ref.providerId, modelId: ref.modelId }
+  }
   if (!ref.provider || !ref.modelId) throw requestError('Fixed agent model requires provider and modelId')
   return {
     mode: 'fixed',
+    source: 'legacy-custom',
     provider: ref.provider,
     modelId: ref.modelId,
     api: ref.api,
@@ -164,14 +181,17 @@ export function modelReferenceSnapshot(modelRef) {
   if (ref.mode !== 'fixed') return { ...AGENT_PROFILE_MODEL_INHERIT }
   return {
     mode: 'fixed',
-    provider: ref.provider,
-    modelId: ref.modelId,
+    ...(ref.source && ref.source !== 'legacy-custom' ? { source: ref.source } : {}),
+    ...(ref.providerId ? { providerId: ref.providerId } : {}),
+    ...(ref.catalogId ? { catalogId: ref.catalogId } : {}),
+    ...(ref.provider ? { provider: ref.provider } : {}),
+    ...(ref.modelId ? { modelId: ref.modelId } : {}),
     ...(ref.api ? { api: ref.api } : {}),
     ...(ref.baseUrl ? { baseUrl: ref.baseUrl } : {}),
   }
 }
 
-export async function resolveAgentProfileModel(profile, parentModel, readStore) {
+export async function resolveAgentProfileModel(profile, parentModel, _readStore, context = {}) {
   const ref = profile?.model || AGENT_PROFILE_MODEL_INHERIT
   if (!ref || ref.mode !== 'fixed') {
     if (!parentModel) throw requestError('No active model is configured for the parent session.')
@@ -179,19 +199,23 @@ export async function resolveAgentProfileModel(profile, parentModel, readStore)
   }
 
   const validRef = validateModelReference(ref)
-  const store = await readStore('custom-providers').catch(() => ({}))
-  const providers = Array.isArray(store) ? store : Object.values(store || {})
-  const configuredModels = providers
-    .flatMap((provider) => Array.isArray(provider?.models) ? provider.models : [])
-    .filter((model) => model && typeof model === 'object')
-  const model = configuredModels.find((candidate) => (
-    candidate.provider === validRef.provider &&
-    candidate.id === validRef.modelId &&
-    (!validRef.api || candidate.api === validRef.api) &&
-    (!validRef.baseUrl || sameBaseUrl(candidate.baseUrl, validRef.baseUrl))
-  ))
-  if (!model) {
-    throw requestError(`Agent profile ${profile?.name || ''} requested model ${validRef.provider}/${validRef.modelId}, but it is not configured.`)
-  }
-  return { model, info: { ...modelReferenceSnapshot(validRef), inherited: false } }
+  const modelRef = validRef.source === 'cloud'
+    ? { version: 1, source: 'cloud', catalogId: validRef.catalogId }
+    : validRef.source === 'custom'
+      ? { version: 1, source: 'custom', providerId: validRef.providerId, modelId: validRef.modelId }
+      : {
+          version: 1,
+          source: 'legacy-custom',
+          provider: validRef.provider,
+          modelId: validRef.modelId,
+          ...(validRef.api ? { api: validRef.api } : {}),
+          ...(validRef.baseUrl ? { baseUrl: validRef.baseUrl } : {}),
+        }
+  const binding = await resolveModelBinding({ modelRef }, {
+    context,
+    currentModel: parentModel,
+    allowCurrentHidden: true,
+    forExecution: true,
+  })
+  return { model: binding.model, modelRef: binding.modelRef, info: { ...modelReferenceSnapshot(validRef), inherited: false } }
 }

package/server/agent-profiles.mjs

@@ -27,7 +27,7 @@ const BUILTIN_OVERRIDES_STORE = 'agent-profile-overrides'
 const RESERVED_NAMES = new Set(subagentDefinitions.map((definition) => definition.name))
 const allowedToolNames = new Set(AGENT_PROFILE_TOOL_NAMES)
 const nameRegex = /^[a-z][a-z0-9_-]{1,39}$/
-const DEFAULT_MAX_RUNTIME_MS = 30 * 60 * 1000
+const DEFAULT_MAX_RUNTIME_MS = 60 * 60 * 1000
 const DEFAULT_MAX_TOOL_CALLS = 300
 const MIGRATION_MARKER_FILE = path.join(userAgentsDir, '.custom-agents-migrated.json')
 let customAgentMigrationPromise = null
@@ -75,7 +75,7 @@ function builtinProfileFromSubagent(definition, override = null) {
     allowedTools: [...definition.allowedTools],
     capabilityPolicy: definition.capabilityPolicy || inferCapabilityPolicy(definition.allowedTools),
     model: modelReferenceSnapshot(override?.model || definition.model),
-    thinkingLevel: 'inherit',
+    thinkingLevel: normalizeAgentProfileThinkingLevel(override?.thinkingLevel || 'inherit'),
     lifecycle: 'builtin',
     managed: true,
     maxRuntimeMs: definition.maxRuntimeMs || DEFAULT_MAX_RUNTIME_MS,
@@ -308,17 +308,36 @@ export async function updateCustomAgentProfile(id, patch) {
   return { ...next, filePath: file, relativePath: `~/.quickforge/agents/${next.name}.md` }
 }
 
-export async function updateBuiltinAgentModelOverride(id, modelInput) {
+export async function updateBuiltinAgentOverrides(id, patch = {}) {
   const current = await getAgentProfile(id)
   if (!current) throw requestError('Agent not found', 404)
-  if (!current.builtin) throw requestError('Only built-in agents support model overrides', 400)
-  const model = validateModelReference(normalizeModelReference(modelInput))
+  if (!current.builtin) throw requestError('Only built-in agents support overrides', 400)
   const overrides = await readStore(BUILTIN_OVERRIDES_STORE).catch(() => ({}))
-  const next = { ...(overrides && typeof overrides === 'object' ? overrides : {}) }
-  if (model.mode === 'fixed') next[current.name] = { model }
-  else delete next[current.name]
+  const base = overrides && typeof overrides === 'object' ? overrides : {}
+  const next = { ...base }
+  const entry = { ...(base[current.name] && typeof base[current.name] === 'object' ? base[current.name] : {}) }
+
+  if (Object.prototype.hasOwnProperty.call(patch, 'model')) {
+    const model = validateModelReference(normalizeModelReference(patch.model))
+    if (model.mode === 'fixed') entry.model = model
+    else delete entry.model
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'thinkingLevel')) {
+    const thinkingLevel = normalizeAgentProfileThinkingLevel(patch.thinkingLevel)
+    if (thinkingLevel === 'inherit') delete entry.thinkingLevel
+    else entry.thinkingLevel = thinkingLevel
+  }
+
+  if (Object.keys(entry).length === 0) delete next[current.name]
+  else next[current.name] = entry
   await writeStore(BUILTIN_OVERRIDES_STORE, next)
-  return { ...current, model: modelReferenceSnapshot(model) }
+
+  const definition = subagentDefinitions.find((item) => item.name === current.name)
+  return builtinProfileFromSubagent(definition, next[current.name] || null)
+}
+
+export async function updateBuiltinAgentModelOverride(id, modelInput) {
+  return updateBuiltinAgentOverrides(id, { model: modelInput })
 }
 
 export async function deleteCustomAgentProfile(id) {

package/server/ai-http-logger.mjs

@@ -3,6 +3,8 @@ import path from 'node:path'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { randomUUID } from 'node:crypto'
 import { streamSimple } from '@earendil-works/pi-ai/compat'
+import { resolveManagedCloudProvider } from './cloud/runtime.mjs'
+import { ensureCloudChatIdempotencyKey } from './cloud/chat-idempotency-store.mjs'
 import {
   DEFAULT_AI_STREAM_DEADLINE_MS,
   withDefaultAiProviderOptions,
@@ -45,14 +47,27 @@ function writeAiHttpRecord(record) {
   })
 }
 
-function headersToRecord(headers) {
+const SENSITIVE_HEADER_NAMES = new Set([
+  'authorization',
+  'proxy-authorization',
+  'x-api-key',
+  'api-key',
+  'idempotency-key',
+  'cookie',
+  'set-cookie',
+])
+
+export function sanitizeHttpHeaders(headers) {
   const result = {}
   if (!headers) return result
 
   try {
     const iterable = typeof headers.entries === 'function' ? headers.entries() : Object.entries(headers)
     for (const [key, value] of iterable) {
-      result[String(key)] = Array.isArray(value) ? value.join(', ') : String(value)
+      const name = String(key)
+      result[name] = SENSITIVE_HEADER_NAMES.has(name.toLowerCase())
+        ? '[REDACTED]'
+        : Array.isArray(value) ? value.join(', ') : String(value)
     }
   } catch {
     // ignore malformed headers
@@ -61,6 +76,10 @@ function headersToRecord(headers) {
   return result
 }
 
+function headersToRecord(headers) {
+  return sanitizeHttpHeaders(headers)
+}
+
 function isRequest(value) {
   return typeof Request !== 'undefined' && value instanceof Request
 }
@@ -253,6 +272,63 @@ function wrapStreamWithDeadline(stream, deadlineController, deadlineMs) {
   }
 }
 
+function lazyStream(streamPromise) {
+  return {
+    result: () => streamPromise.then((stream) => stream.result()),
+    [Symbol.asyncIterator]() {
+      let iteratorPromise
+      const iterator = () => {
+        iteratorPromise ||= streamPromise.then((stream) => stream[Symbol.asyncIterator]())
+        return iteratorPromise
+      }
+      return {
+        next: async () => (await iterator()).next(),
+        return: async () => {
+          const resolved = await iterator()
+          if (typeof resolved.return === 'function') return resolved.return()
+          return { value: undefined, done: true }
+        },
+      }
+    },
+  }
+}
+
+function createProviderStream(model, context, options) {
+  return aiHttpLogEnabled
+    ? aiHttpContext.run({
+        traceId: randomUUID(),
+        sessionId: options.sessionId,
+        purpose: options.metadata?.quickforgePurpose || 'chat',
+        provider: model?.provider,
+        api: model?.api,
+        model: model?.id,
+      }, () => streamSimple(model, context, options))
+    : streamSimple(model, context, options)
+}
+
+const CLIENT_MESSAGE_ID_FIELD = 'quickforgeClientMessageId'
+
+function logicalMessageIdFromContext(context) {
+  const messages = Array.isArray(context?.messages) ? context.messages : []
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index]
+    if (message?.role !== 'user' && message?.role !== 'user-with-attachments') continue
+    const metadata = message.metadata
+    const messageId = metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+      ? metadata[CLIENT_MESSAGE_ID_FIELD]
+      : undefined
+    return typeof messageId === 'string' && messageId ? messageId : undefined
+  }
+  return undefined
+}
+
+async function managedCloudIdempotencyKey(context, options) {
+  const messageId = logicalMessageIdFromContext(context)
+  return options.sessionId && messageId
+    ? ensureCloudChatIdempotencyKey(options.sessionId, messageId)
+    : randomUUID()
+}
+
 export function streamSimpleWithAiHttpLogging(model, context, options = {}) {
   const providerOptions = withDefaultAiProviderOptions(options)
   const deadlineMs = Number.isFinite(providerOptions.deadlineMs)
@@ -265,16 +341,26 @@ export function streamSimpleWithAiHttpLogging(model, context, options = {}) {
   }
   delete effectiveOptions.deadlineMs
 
-  const stream = aiHttpLogEnabled
-    ? aiHttpContext.run({
-        traceId: randomUUID(),
-        sessionId: effectiveOptions.sessionId,
-        purpose: effectiveOptions.metadata?.quickforgePurpose || 'chat',
-        provider: model?.provider,
-        api: model?.api,
-        model: model?.id,
-      }, () => streamSimple(model, context, effectiveOptions))
-    : streamSimple(model, context, effectiveOptions)
+  const managedCloud = model?.provider === 'quickforge-cloud' && model?.quickforgeModelSource === 'cloud'
+  const stream = managedCloud
+    ? lazyStream(Promise.all([
+        resolveManagedCloudProvider(model, effectiveOptions.signal),
+        managedCloudIdempotencyKey(context, effectiveOptions),
+      ]).then(([resolved, idempotencyKey]) => createProviderStream(
+        {
+          ...resolved.model,
+          headers: {
+            ...(resolved.model.headers || {}),
+            'Idempotency-Key': idempotencyKey,
+          },
+        },
+        context,
+        {
+          ...effectiveOptions,
+          apiKey: resolved.apiKey,
+        },
+      )))
+    : createProviderStream(model, context, effectiveOptions)
 
   return wrapStreamWithDeadline(stream, deadlineController, deadlineMs)
 }

package/server/auto-compaction.mjs

@@ -18,6 +18,14 @@ export const DEFAULT_AUTO_COMPACT_SETTINGS = {
   requireConfirmation: true,
 }
 
+/**
+ * 保留尾部（最近回合）的字符预算上限。当会话以工具消息为主、user 回合
+ * 稀疏时，按 keepRecentTurns 从尾部回溯会跨越大量工具消息，导致压缩
+ * 范围过小甚至为空（tailStart 与 compactedUpToIndex 重合）。达到该预算
+ * 时按当前用户轮次起点截断，将更早的完整工具链历史并入压缩范围。
+ */
+export const DEFAULT_MAX_TAIL_CHARS = 40000
+
 const AUTO_COMPACT_MIN_INTERVAL_MS = 30_000
 const AUTO_COMPACT_REJECTION_SUPPRESS_MS = 10 * 60_000
 
@@ -64,11 +72,13 @@ function contentToText(content) {
   }).filter(Boolean).join('\n')
 }
 
+function messageChars(message) {
+  if (!message || typeof message !== 'object') return 0
+  return [message.role || '', contentToText(message.content), safeJson(message.attachments)].join('\n').length
+}
+
 function estimateMessagesChars(messages) {
-  return (Array.isArray(messages) ? messages : []).reduce((total, message) => {
-    if (!message || typeof message !== 'object') return total
-    return total + [message.role || '', contentToText(message.content), safeJson(message.attachments)].join('\n').length
-  }, 0)
+  return (Array.isArray(messages) ? messages : []).reduce((total, message) => total + messageChars(message), 0)
 }
 
 function isUserMessage(message) {
@@ -76,13 +86,26 @@ function isUserMessage(message) {
     && !isCompactSummaryMessage(message)
 }
 
-function tailStartForRecentTurns(messages, keepRecentTurns) {
+function isToolResultMessage(message) {
+  return message?.role === 'toolResult'
+}
+
+export function tailStartForRecentTurns(messages, keepRecentTurns, maxTailChars = DEFAULT_MAX_TAIL_CHARS) {
   const source = Array.isArray(messages) ? messages : []
   let seenUserTurns = 0
+  let tailChars = 0
   for (let index = source.length - 1; index >= 0; index--) {
-    if (!isUserMessage(source[index])) continue
-    seenUserTurns += 1
+    if (isUserMessage(source[index])) seenUserTurns += 1
+    tailChars += messageChars(source[index])
     if (seenUserTurns >= keepRecentTurns) return index
+    // 保留的尾部超过预算：仍按完整用户轮次切分，避免把当前运行中的
+    // assistant/toolResult 链从中间截断，导致压缩线落在一轮对话内部。
+    if (tailChars >= maxTailChars) {
+      for (let turnStart = index; turnStart >= 0; turnStart--) {
+        if (isUserMessage(source[turnStart])) return turnStart
+      }
+      return 0
+    }
   }
   return 0
 }
@@ -145,7 +168,11 @@ export function buildAutoCompactLoopMessages(session, messages) {
   if (!summaryMessage) return messages
   const source = Array.isArray(messages) ? messages : []
   const compactedUpToIndex = Math.min(source.length, Math.max(0, Number(session.contextCompaction?.compactedUpToIndex) || 0))
-  return [summaryMessage, ...source.slice(compactedUpToIndex)]
+  // 防御旧持久化数据：compactedUpToIndex 可能指向 toolResult，跳过开头的孤儿，
+  // 避免压缩后的消息序列以 tool 消息开头（LLM API 会拒绝孤立 tool 消息）
+  let tailStart = compactedUpToIndex
+  while (tailStart < source.length && isToolResultMessage(source[tailStart])) tailStart += 1
+  return [summaryMessage, ...source.slice(tailStart)]
 }
 
 export async function compactSessionInPlace({

package/server/cloud/chat-idempotency-store.mjs

@@ -0,0 +1,96 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { ensureStorage, storageDir } from '../storage.mjs'
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const MESSAGE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function assertIdentifier(value, label, pattern) {
+  const normalized = typeof value === 'string' ? value.trim() : ''
+  if (!pattern.test(normalized)) throw new Error(`Invalid ${label}.`)
+  return normalized
+}
+
+export function createCloudChatIdempotencyStore({
+  directory = path.join(storageDir, 'security', 'cloud-chat-idempotency'),
+  ensureBaseStorage = ensureStorage,
+} = {}) {
+  function entryPath(sessionId, messageId) {
+    return path.join(directory, digest(sessionId), `${digest(messageId)}.json`)
+  }
+
+  async function ensureDirectory(file) {
+    await ensureBaseStorage()
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  }
+
+  async function readEntry(file, sessionId, messageId) {
+    try {
+      const raw = await fs.readFile(file, 'utf8')
+      const entry = raw.trim() ? JSON.parse(raw) : null
+      if (entry?.sessionId !== sessionId || entry?.messageId !== messageId || !UUID_PATTERN.test(entry?.idempotencyKey || '')) {
+        throw new Error('Invalid QuickForge Cloud chat idempotency record.')
+      }
+      return entry
+    } catch (error) {
+      if (error?.code === 'ENOENT') return null
+      throw error
+    }
+  }
+
+  async function ensure(sessionIdInput, messageIdInput) {
+    const sessionId = assertIdentifier(sessionIdInput, 'session ID', /^.{1,512}$/)
+    const messageId = assertIdentifier(messageIdInput, 'logical message ID', MESSAGE_ID_PATTERN)
+    const file = entryPath(sessionId, messageId)
+    await ensureDirectory(file)
+
+    const existing = await readEntry(file, sessionId, messageId)
+    if (existing) return existing.idempotencyKey
+
+    const entry = {
+      schemaVersion: 1,
+      sessionId,
+      messageId,
+      idempotencyKey: randomUUID(),
+      createdAt: new Date().toISOString(),
+    }
+
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`
+    await fs.writeFile(temporary, `${JSON.stringify(entry, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 })
+    try { await fs.chmod(temporary, 0o600) } catch { /* best effort on Windows */ }
+    try {
+      await fs.link(temporary, file)
+      try { await fs.chmod(file, 0o600) } catch { /* best effort on Windows */ }
+      return entry.idempotencyKey
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      const concurrent = await readEntry(file, sessionId, messageId)
+      if (!concurrent) throw error
+      return concurrent.idempotencyKey
+    } finally {
+      await fs.rm(temporary, { force: true })
+    }
+  }
+
+  async function removeSession(sessionIdInput) {
+    const sessionId = assertIdentifier(sessionIdInput, 'session ID', /^.{1,512}$/)
+    await fs.rm(path.join(directory, digest(sessionId)), { recursive: true, force: true })
+  }
+
+  return { directory, ensure, removeSession }
+}
+
+const defaultStore = createCloudChatIdempotencyStore()
+
+export function ensureCloudChatIdempotencyKey(sessionId, messageId) {
+  return defaultStore.ensure(sessionId, messageId)
+}
+
+export function deleteCloudChatIdempotencySession(sessionId) {
+  return defaultStore.removeSession(sessionId)
+}

package/server/cloud/client.mjs

@@ -0,0 +1,99 @@
+import { cloudEndpoint } from './config.mjs'
+
+export class CloudApiError extends Error {
+  constructor(message, { status = 0, code = 'cloud_request_failed', retryable = false, details } = {}) {
+    super(message)
+    this.name = 'CloudApiError'
+    this.status = status
+    this.code = code
+    this.retryable = retryable
+    this.details = details
+  }
+}
+
+async function parseError(response) {
+  let payload
+  try { payload = await response.json() } catch { payload = undefined }
+  const error = payload?.error
+  const structured = error && typeof error === 'object' ? error : undefined
+  const oauthCode = typeof error === 'string' ? error : undefined
+  return new CloudApiError(
+    structured?.message || payload?.error_description || `QuickForge Cloud request failed (${response.status}).`,
+    {
+      status: response.status,
+      code: structured?.code || payload?.code || oauthCode || 'cloud_request_failed',
+      retryable: Boolean(structured?.retryable || payload?.retryable),
+      details: structured?.details || payload?.details,
+    },
+  )
+}
+
+function timeoutSignal(timeoutMs, outerSignal) {
+  const timeout = AbortSignal.timeout(timeoutMs)
+  return outerSignal ? AbortSignal.any([outerSignal, timeout]) : timeout
+}
+
+export class CloudClient {
+  constructor({ baseUrl, timeoutMs = 10_000, fetchImpl = fetch } = {}) {
+    if (!(baseUrl instanceof URL)) throw new Error('CloudClient requires a configured base URL.')
+    this.baseUrl = baseUrl
+    this.timeoutMs = timeoutMs
+    this.fetch = fetchImpl
+  }
+
+  async request(pathname, { method = 'GET', token, body, headers, signal, raw = false, timeout = true } = {}) {
+    const requestHeaders = { Accept: 'application/json', ...headers }
+    if (body !== undefined) requestHeaders['Content-Type'] = 'application/json'
+    if (token) requestHeaders.Authorization = `Bearer ${token}`
+    const response = await this.fetch(cloudEndpoint(this.baseUrl, pathname), {
+      method,
+      headers: requestHeaders,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: timeout ? timeoutSignal(this.timeoutMs, signal) : signal,
+      redirect: 'error',
+    })
+    if (!response.ok) throw await parseError(response)
+    if (raw) return response
+    if (response.status === 204) return undefined
+    return response.json()
+  }
+
+  health(signal) { return this.request('healthz', { signal }) }
+  ready(signal) { return this.request('readyz', { signal }) }
+  refresh(refreshToken, signal) {
+    return this.request('oauth/token', {
+      method: 'POST', body: { grantType: 'refresh_token', refreshToken }, signal,
+    })
+  }
+  authorizeDevice({ installationId, clientId = 'quickforge-desktop', publicKey, installationName, platform, clientVersion, signal } = {}) {
+    return this.request('oauth/device_authorization', {
+      method: 'POST',
+      body: { installationId, clientId, publicKey, installationName, platform, clientVersion },
+      signal,
+    })
+  }
+  exchangeDeviceCode(deviceCode, clientId = 'quickforge-desktop', signal) {
+    return this.request('oauth/token', {
+      method: 'POST',
+      body: {
+        grantType: 'urn:ietf:params:oauth:grant-type:device_code',
+        deviceCode,
+        clientId,
+      },
+      signal,
+    })
+  }
+  me(token, signal) { return this.request('v1/me', { token, signal }) }
+  models(token, signal) { return this.request('v1/models', { token, signal }) }
+  usage(token, signal) { return this.request('v1/usage', { token, signal }) }
+  installations(token, signal) { return this.request('v1/installations', { token, signal }) }
+  revokeInstallation(token, installationId, signal) {
+    return this.request(`v1/installations/${encodeURIComponent(installationId)}`, { method: 'DELETE', token, signal })
+  }
+  chat(token, payload, idempotencyKey, signal) {
+    return this.request('v1/chat/completions', {
+      method: 'POST', token, body: payload,
+      headers: { 'Idempotency-Key': idempotencyKey }, signal, raw: true, timeout: false,
+    })
+  }
+}