@shawnstack/quickforge 1.7.3 → 1.7.5

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

package/server/ai-http-logger.mjs

@@ -3,7 +3,12 @@ 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 { withDefaultAiProviderOptions } from './ai-provider-options.mjs'
+import { resolveManagedCloudProvider } from './cloud/runtime.mjs'
+import { ensureCloudChatIdempotencyKey } from './cloud/chat-idempotency-store.mjs'
+import {
+  DEFAULT_AI_STREAM_DEADLINE_MS,
+  withDefaultAiProviderOptions,
+} from './ai-provider-options.mjs'
 import { logsDir } from './storage.mjs'
 
 const PATCH_MARKER = Symbol.for('quickforge.aiHttpLogger.fetchPatched')
@@ -42,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
@@ -58,6 +76,10 @@ function headersToRecord(headers) {
   return result
 }
 
+function headersToRecord(headers) {
+  return sanitizeHttpHeaders(headers)
+}
+
 function isRequest(value) {
   return typeof Request !== 'undefined' && value instanceof Request
 }
@@ -206,18 +228,139 @@ export function installAiHttpLogger() {
   globalThis[PATCH_MARKER] = true
 }
 
+function combineAbortSignals(parentSignal, deadlineSignal) {
+  if (!parentSignal) return deadlineSignal
+  if (typeof AbortSignal.any === 'function') return AbortSignal.any([parentSignal, deadlineSignal])
+
+  const controller = new AbortController()
+  const abort = () => controller.abort()
+  if (parentSignal.aborted || deadlineSignal.aborted) {
+    controller.abort()
+  } else {
+    parentSignal.addEventListener('abort', abort, { once: true })
+    deadlineSignal.addEventListener('abort', abort, { once: true })
+  }
+  return controller.signal
+}
+
+function wrapStreamWithDeadline(stream, deadlineController, deadlineMs) {
+  let timer
+  const deadlinePromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      deadlineController.abort()
+      reject(new Error(`AI stream timed out after ${deadlineMs}ms`))
+    }, deadlineMs)
+    timer.unref?.()
+  })
+  const resultPromise = Promise.race([stream.result(), deadlinePromise])
+    .finally(() => clearTimeout(timer))
+  resultPromise.catch(() => {})
+
+  return {
+    result: () => resultPromise,
+    [Symbol.asyncIterator]() {
+      const iterator = stream[Symbol.asyncIterator]()
+      return {
+        next: () => Promise.race([iterator.next(), deadlinePromise]),
+        return: async () => {
+          clearTimeout(timer)
+          if (typeof iterator.return === 'function') return iterator.return()
+          return { value: undefined, done: true }
+        },
+      }
+    },
+  }
+}
+
+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)
-  if (!aiHttpLogEnabled) return streamSimple(model, context, providerOptions)
-
-  const traceContext = {
-    traceId: randomUUID(),
-    sessionId: providerOptions.sessionId,
-    purpose: providerOptions.metadata?.quickforgePurpose || 'chat',
-    provider: model?.provider,
-    api: model?.api,
-    model: model?.id,
+  const deadlineMs = Number.isFinite(providerOptions.deadlineMs)
+    ? Math.max(1, providerOptions.deadlineMs)
+    : DEFAULT_AI_STREAM_DEADLINE_MS
+  const deadlineController = new AbortController()
+  const effectiveOptions = {
+    ...providerOptions,
+    signal: combineAbortSignals(providerOptions.signal, deadlineController.signal),
   }
+  delete effectiveOptions.deadlineMs
+
+  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 aiHttpContext.run(traceContext, () => streamSimple(model, context, providerOptions))
+  return wrapStreamWithDeadline(stream, deadlineController, deadlineMs)
 }

package/server/ai-provider-options.mjs

@@ -1,8 +1,11 @@
 export const DEFAULT_AI_MAX_RETRIES = 3
+export const DEFAULT_AI_HTTP_TIMEOUT_MS = 2 * 60 * 1000
+export const DEFAULT_AI_STREAM_DEADLINE_MS = 5 * 60 * 1000
 
 export function withDefaultAiProviderOptions(options = {}) {
   return {
     maxRetries: DEFAULT_AI_MAX_RETRIES,
+    timeoutMs: DEFAULT_AI_HTTP_TIMEOUT_MS,
     ...options,
   }
 }

package/server/channels/channel-logs.mjs

@@ -0,0 +1,13 @@
+import path from 'node:path'
+
+function safeChannelId(channelId) {
+  const safeId = String(channelId || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return safeId || 'channel'
+}
+
+export function channelLogsDirectory(logsDir, channelId) {
+  return path.join(path.resolve(logsDir), 'channels', safeChannelId(channelId))
+}

package/server/channels/event-relay.mjs

@@ -0,0 +1,33 @@
+const CHANNEL_EVENTS_URL_ENV = 'QUICKFORGE_CHANNEL_EVENTS_URL'
+const CHANNEL_EVENT_ACTION = 'channel-event'
+const RELAY_TIMEOUT_MS = 3000
+
+export async function publishChannelSessionChanged(event) {
+  const url = process.env[CHANNEL_EVENTS_URL_ENV]
+  if (!url) return false
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), RELAY_TIMEOUT_MS)
+  timer.unref?.()
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-quickforge-action': CHANNEL_EVENT_ACTION,
+      },
+      body: JSON.stringify({
+        ...event,
+        type: 'sessions-changed',
+        timestamp: event.timestamp || new Date().toISOString(),
+      }),
+      signal: controller.signal,
+    })
+    return response.ok
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/server/channels/process-channel.mjs

@@ -1,7 +1,11 @@
 /* eslint-disable no-control-regex -- ANSI escape matching intentionally includes ESC. */
 import { spawn } from 'node:child_process'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
 import { EventEmitter } from 'node:events'
 import { setTimeout as delay } from 'node:timers/promises'
+import { channelLogsDirectory } from './channel-logs.mjs'
+import { logger } from '../utils/logger.mjs'
 
 const DEFAULT_LOG_LIMIT = 300
 const STOP_TIMEOUT_MS = 5000
@@ -55,6 +59,9 @@ export class ProcessChannelProvider extends EventEmitter {
     super()
     this.definition = definition
     this.logLimit = options.logLimit || DEFAULT_LOG_LIMIT
+    this.logsDir = options.logsDir
+    this.logWriteErrorReported = false
+    this.logWritePromise = Promise.resolve()
     this.status = 'stopped'
     this.process = null
     this.pid = null
@@ -118,6 +125,27 @@ export class ProcessChannelProvider extends EventEmitter {
     this.emitEvent('status', { status, snapshot: this.snapshot() })
   }
 
+  persistLog(entry) {
+    if (!this.logsDir) return
+    const directory = channelLogsDirectory(this.logsDir, this.definition.id)
+    const filePath = path.join(directory, `channel-${entry.time.slice(0, 10)}.log`)
+    const line = `${JSON.stringify({ time: entry.time, stream: entry.stream, text: entry.text })}\n`
+    this.logWritePromise = this.logWritePromise
+      .then(() => fs.mkdir(directory, { recursive: true }))
+      .then(() => fs.appendFile(filePath, line, 'utf8'))
+      .then(() => {
+        this.logWriteErrorReported = false
+      })
+      .catch((error) => {
+        if (this.logWriteErrorReported) return
+        this.logWriteErrorReported = true
+        logger.warn('Failed to persist channel log.', {
+          channelId: this.definition.id,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      })
+  }
+
   addLog(stream, text) {
     if (!text) return
     const entry = {
@@ -131,6 +159,7 @@ export class ProcessChannelProvider extends EventEmitter {
       this.logs.splice(0, this.logs.length - this.logLimit)
     }
     this.emitEvent('log', { log: entry })
+    this.persistLog(entry)
   }
 
   addProcessText(stream, text) {

package/server/channels/providers/wechat.mjs

@@ -4,6 +4,7 @@ import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { ProcessChannelProvider } from '../process-channel.mjs'
 import { getDefaultWorkspaceRoot, readProjectConfig } from '../../project-config.mjs'
+import { createNodeProcessEnv } from '../../utils/process-env.mjs'
 
 const WEIXIN_ACP_PACKAGE = 'weixin-acp'
 const MIN_NODE_MAJOR = 22
@@ -134,7 +135,7 @@ function runCommand(command, args, options = {}) {
 }
 
 export class WechatChannelProvider extends ProcessChannelProvider {
-  constructor({ projectRoot }) {
+  constructor({ projectRoot, channelEventsUrl, logsDir }) {
     super({
       id: 'wechat',
       name: '微信',
@@ -149,8 +150,9 @@ export class WechatChannelProvider extends ProcessChannelProvider {
         { id: 'relogin', label: '重新登录' },
       ],
       requirements: [`Node.js >= ${MIN_NODE_MAJOR}`, 'npm/npx 可用', '首次启动需要微信扫码登录'],
-    })
+    }, { logsDir })
     this.projectRoot = projectRoot
+    this.channelEventsUrl = channelEventsUrl
     this.launchWorkspace = null
   }
 
@@ -179,7 +181,11 @@ export class WechatChannelProvider extends ProcessChannelProvider {
       command: npxCommand(),
       args: ['-y', WEIXIN_ACP_PACKAGE, 'start', '--', acpCommand, ...acpArgs],
       cwd: this.launchWorkspace?.path || getDefaultWorkspaceRoot() || this.projectRoot,
-      env: process.env,
+      env: createNodeProcessEnv(process.env, {
+        QUICKFORGE_ACP_CHANNEL_ID: this.definition.id,
+        QUICKFORGE_ACP_CHANNEL_NAME: this.definition.name,
+        ...(this.channelEventsUrl ? { QUICKFORGE_CHANNEL_EVENTS_URL: this.channelEventsUrl } : {}),
+      }),
       shell: shouldUseShellForNpx(),
     }
   }

package/server/channels/registry.mjs

@@ -16,7 +16,11 @@ function attachProvider(provider) {
 export function initializeChannels(options = {}) {
   if (initialized) return
   initialized = true
-  attachProvider(createWechatChannelProvider({ projectRoot: options.projectRoot }))
+  attachProvider(createWechatChannelProvider({
+    projectRoot: options.projectRoot,
+    channelEventsUrl: options.channelEventsUrl,
+    logsDir: options.logsDir,
+  }))
 }
 
 function requireProvider(id) {

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)
+}