@shawnstack/quickforge 1.6.7 → 1.6.9

package/server/agent-profiles.mjs

@@ -1,17 +1,36 @@
+import { existsSync, promises as fs } from 'node:fs'
+import path from 'node:path'
 import { randomUUID } from 'node:crypto'
-import { readStore, atomicUpdate } from './storage.mjs'
-import { subagentDefinitions } from './subagents.mjs'
+import { readStore, userAgentsDir, writeStore } from './storage.mjs'
+import { builtinSubagentProfilePath, ensureBuiltinSubagentMarkdownFiles, subagentDefinitions } from './subagents.mjs'
 import { workspaceTools } from './tools/definitions.mjs'
 import { defaultGlobalWorkspaceContext, projectContextFromId } from './project-config.mjs'
-import { loadFileAgentProfiles } from './agent-profile-files.mjs'
+import {
+  deleteUserAgentProfileMarkdown,
+  loadFileAgentProfiles,
+  userAgentProfileFilePath,
+  writeUserAgentProfileMarkdown,
+} from './agent-profile-files.mjs'
+import {
+  AGENT_PROFILE_TOOL_NAMES,
+  inferCapabilityPolicy,
+  modelReferenceSnapshot,
+  normalizeAgentProfileThinkingLevel,
+  normalizeCapabilityPolicy,
+  normalizeModelReference,
+  validateAgentProfileTools,
+  validateModelReference,
+} from './agent-profile-schema.mjs'
 
 const STORE = 'custom-agents'
+const BUILTIN_OVERRIDES_STORE = 'agent-profile-overrides'
 const RESERVED_NAMES = new Set(subagentDefinitions.map((definition) => definition.name))
-export const AGENT_PROFILE_TOOL_NAMES = ['read_file', 'grep_files', 'write_file', 'edit_file', 'run_command']
 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_TOOL_CALLS = 300
+const MIGRATION_MARKER_FILE = path.join(userAgentsDir, '.custom-agents-migrated.json')
+let customAgentMigrationPromise = null
 
 function requestError(message, statusCode = 400) {
   const error = new Error(message)
@@ -46,7 +65,7 @@ function normalizeOptionalRuntime(value, fallback) {
   return Math.min(Math.max(Math.round(parsed), 1000), DEFAULT_MAX_RUNTIME_MS)
 }
 
-function builtinProfileFromSubagent(definition) {
+function builtinProfileFromSubagent(definition, override = null) {
   return {
     id: definition.name,
     name: definition.name,
@@ -54,20 +73,28 @@ function builtinProfileFromSubagent(definition) {
     description: definition.description || '',
     systemPrompt: definition.systemPrompt || '',
     allowedTools: [...definition.allowedTools],
+    capabilityPolicy: definition.capabilityPolicy || inferCapabilityPolicy(definition.allowedTools),
+    model: modelReferenceSnapshot(override?.model || definition.model),
+    thinkingLevel: 'inherit',
+    lifecycle: 'builtin',
+    managed: true,
     maxRuntimeMs: definition.maxRuntimeMs || DEFAULT_MAX_RUNTIME_MS,
     maxToolCalls: definition.maxToolCalls || DEFAULT_MAX_TOOL_CALLS,
     enabledAsSubagent: true,
     builtin: true,
     source: 'builtin',
     readonly: true,
+    filePath: builtinSubagentProfilePath(definition.name),
+    relativePath: `~/.quickforge/agents/builtin/${definition.name}.md`,
     allowFileMutations: definition.allowFileMutations === true,
     createdAt: 'builtin',
     updatedAt: 'builtin',
   }
 }
 
-export function listBuiltinAgentProfiles() {
-  return subagentDefinitions.map(builtinProfileFromSubagent)
+export async function listBuiltinAgentProfiles() {
+  const overrides = await readStore(BUILTIN_OVERRIDES_STORE).catch(() => ({}))
+  return subagentDefinitions.map((definition) => builtinProfileFromSubagent(definition, overrides?.[definition.name]))
 }
 
 function normalizeProfileInput(input, existing = null, { creating = false } = {}) {
@@ -85,6 +112,13 @@ function normalizeProfileInput(input, existing = null, { creating = false } = {}
   for (const toolName of allowedTools) {
     if (!allowedToolNames.has(toolName)) throw requestError(`Unsupported tool for custom agent: ${toolName}`)
   }
+  const capabilityPolicy = normalizeCapabilityPolicy(
+    input?.capabilityPolicy ?? existing?.capabilityPolicy,
+    allowedTools,
+  )
+  validateAgentProfileTools(allowedTools, capabilityPolicy)
+  const model = validateModelReference(normalizeModelReference(input?.model ?? existing?.model))
+  const thinkingLevel = normalizeAgentProfileThinkingLevel(input?.thinkingLevel ?? existing?.thinkingLevel)
 
   return {
     id: existing?.id || `agent-${randomUUID()}`,
@@ -93,12 +127,18 @@ function normalizeProfileInput(input, existing = null, { creating = false } = {}
     description: String(input?.description ?? existing?.description ?? '').trim().slice(0, 500),
     systemPrompt: String(input?.systemPrompt ?? existing?.systemPrompt ?? '').trim(),
     allowedTools,
+    capabilityPolicy,
+    model,
+    thinkingLevel,
+    lifecycle: existing?.lifecycle || 'persistent',
     maxRuntimeMs: normalizeOptionalRuntime(input?.maxRuntimeMs ?? existing?.maxRuntimeMs, DEFAULT_MAX_RUNTIME_MS),
     maxToolCalls: normalizeOptionalPositiveInteger(input?.maxToolCalls ?? existing?.maxToolCalls, DEFAULT_MAX_TOOL_CALLS, 300),
     enabledAsSubagent: input?.enabledAsSubagent === undefined ? Boolean(existing?.enabledAsSubagent ?? true) : input.enabledAsSubagent === true,
     builtin: false,
-    source: 'store',
+    source: 'user',
     readonly: false,
+    managed: true,
+    managedBy: 'quickforge',
     allowFileMutations: allowedTools.some((toolName) => toolName === 'write_file' || toolName === 'edit_file'),
     createdAt: existing?.createdAt || now,
     updatedAt: now,
@@ -110,6 +150,74 @@ async function readCustomAgentMap() {
   return data && typeof data === 'object' ? data : {}
 }
 
+function migrationReportEntry(profile, file, extra = {}) {
+  return {
+    id: profile.id,
+    fromName: profile.name,
+    toName: path.basename(file, '.md'),
+    file,
+    ...extra,
+  }
+}
+
+function uniqueMigratedName(name, usedNames) {
+  const base = String(name || '').trim().toLowerCase()
+  const candidates = [base, `${base}-store`, `${base}-custom`]
+  for (const candidate of candidates) {
+    if (nameRegex.test(candidate) && !usedNames.has(candidate) && !RESERVED_NAMES.has(candidate) && !existsSync(userAgentProfileFilePath(candidate))) return candidate
+  }
+  for (let index = 2; index < 100; index += 1) {
+    const candidate = `${base.slice(0, 34)}-${index}`
+    if (nameRegex.test(candidate) && !usedNames.has(candidate) && !RESERVED_NAMES.has(candidate) && !existsSync(userAgentProfileFilePath(candidate))) return candidate
+  }
+  return null
+}
+
+async function migrateCustomAgentStoreToFiles() {
+  if (existsSync(MIGRATION_MARKER_FILE)) return
+  await fs.mkdir(userAgentsDir, { recursive: true })
+  const custom = Object.values(await readCustomAgentMap())
+  const report = { migratedAt: new Date().toISOString(), sourceStore: STORE, migrated: [], conflicts: [], skipped: [] }
+  if (custom.length === 0) {
+    await fs.writeFile(MIGRATION_MARKER_FILE, JSON.stringify(report, null, 2), 'utf8')
+    return
+  }
+
+  const usedNames = new Set()
+  for (const item of custom) {
+    try {
+      const profile = normalizeProfileInput({ ...item, id: item.id }, item)
+      let targetName = profile.name
+      let conflictReason = ''
+      if (RESERVED_NAMES.has(targetName) || existsSync(userAgentProfileFilePath(targetName)) || usedNames.has(targetName)) {
+        conflictReason = RESERVED_NAMES.has(targetName) ? 'reserved builtin name or duplicate' : 'target file already exists or duplicate'
+        targetName = uniqueMigratedName(targetName, usedNames)
+      }
+      if (!targetName) {
+        report.skipped.push({ id: item?.id, fromName: item?.name, reason: 'unable to allocate unique markdown file name' })
+        continue
+      }
+      const migrated = { ...profile, name: targetName, source: 'user', readonly: false, managed: true, managedBy: 'quickforge' }
+      const file = await writeUserAgentProfileMarkdown(migrated)
+      usedNames.add(targetName)
+      const entry = migrationReportEntry(item, file, conflictReason ? { reason: conflictReason } : {})
+      if (conflictReason) report.conflicts.push(entry)
+      else report.migrated.push(entry)
+    } catch (error) {
+      report.skipped.push({ id: item?.id, fromName: item?.name, reason: error?.message || String(error) })
+    }
+  }
+  await fs.writeFile(MIGRATION_MARKER_FILE, JSON.stringify(report, null, 2), 'utf8')
+}
+
+async function ensureCustomAgentStoreMigrated() {
+  if (existsSync(MIGRATION_MARKER_FILE)) return
+  customAgentMigrationPromise ||= migrateCustomAgentStoreToFiles().finally(() => {
+    customAgentMigrationPromise = null
+  })
+  await customAgentMigrationPromise
+}
+
 async function resolveWorkspaceRoot(options = {}) {
   if (options.workspaceRoot) return options.workspaceRoot
   if (options.projectId) {
@@ -146,10 +254,11 @@ function mergeProfiles({ builtin = [], file = [], custom = [] }) {
 }
 
 export async function listAgentProfiles(options = {}) {
-  const custom = Object.values(await readCustomAgentMap())
+  await ensureBuiltinSubagentMarkdownFiles()
+  await ensureCustomAgentStoreMigrated()
   const workspaceRoot = await resolveWorkspaceRoot(options)
   const file = await loadFileAgentProfiles(workspaceRoot, { reservedNames: RESERVED_NAMES })
-  const profiles = mergeProfiles({ builtin: listBuiltinAgentProfiles(), file, custom })
+  const profiles = mergeProfiles({ builtin: await listBuiltinAgentProfiles(), file, custom: [] })
   return options.includeDisabled ? profiles : profiles.filter((profile) => profile.enabledAsSubagent || profile.builtin || profile.enabledAsSubagent === false)
 }
 
@@ -163,46 +272,60 @@ export async function getAgentProfile(idOrName, options = {}) {
   const profiles = await listAgentProfiles({ ...options, includeDisabled: true })
   const byName = profiles.find((profile) => profile.name === key)
   if (byName) return byName
-  const custom = Object.values(await readCustomAgentMap())
-  return custom.find((profile) => profile?.id === key) || profiles.find((profile) => profile.id === key) || null
+  return profiles.find((profile) => String(profile.id || '').toLowerCase() === key) || null
+}
+
+function assertEditableUserProfile(profile) {
+  if (!profile) throw requestError('Agent not found', 404)
+  if (profile.builtin) throw requestError('Built-in agents cannot be modified', 403)
+  if (profile.readonly) throw requestError('Read-only agents cannot be modified from the API', 403)
+  if (profile.source !== 'user' || profile.managedBy !== 'quickforge') throw requestError('Only QuickForge-managed user agents can be modified from the API', 403)
+}
+
+async function assertNameAvailable(name, currentId = null) {
+  if (RESERVED_NAMES.has(name)) throw requestError(`Agent name is reserved: ${name}`, 409)
+  const existing = await listAgentProfiles({ includeDisabled: true })
+  const conflict = existing.find((profile) => profile.name === name && profile.id !== currentId)
+  if (conflict) throw requestError(`Agent name already exists: ${name}`, 409)
 }
 
 export async function createCustomAgentProfile(input) {
-  let created = null
-  await atomicUpdate(STORE, (data) => {
-    const map = data && typeof data === 'object' ? data : {}
-    const profile = normalizeProfileInput(input, null, { creating: true })
-    if (Object.values(map).some((item) => item?.name === profile.name)) throw requestError(`Agent name already exists: ${profile.name}`, 409)
-    created = profile
-    map[profile.id] = profile
-    return map
-  })
-  return created
+  await ensureCustomAgentStoreMigrated()
+  const profile = normalizeProfileInput(input, null, { creating: true })
+  await assertNameAvailable(profile.name)
+  const file = await writeUserAgentProfileMarkdown(profile)
+  return { ...profile, filePath: file, relativePath: `~/.quickforge/agents/${profile.name}.md` }
 }
 
 export async function updateCustomAgentProfile(id, patch) {
-  let updated = null
-  await atomicUpdate(STORE, (data) => {
-    const map = data && typeof data === 'object' ? data : {}
-    const current = map[id]
-    if (!current) throw requestError('Agent not found', 404)
-    const next = normalizeProfileInput(patch, current)
-    if (RESERVED_NAMES.has(next.name)) throw requestError(`Agent name is reserved: ${next.name}`, 409)
-    if (Object.values(map).some((item) => item?.id !== id && item?.name === next.name)) throw requestError(`Agent name already exists: ${next.name}`, 409)
-    updated = next
-    map[id] = next
-    return map
-  })
-  return updated
+  await ensureCustomAgentStoreMigrated()
+  const current = await getAgentProfile(id)
+  assertEditableUserProfile(current)
+  const next = normalizeProfileInput(patch, current)
+  await assertNameAvailable(next.name, current.id)
+  const file = await writeUserAgentProfileMarkdown(next)
+  if (next.name !== current.name) await deleteUserAgentProfileMarkdown(current)
+  return { ...next, filePath: file, relativePath: `~/.quickforge/agents/${next.name}.md` }
+}
+
+export async function updateBuiltinAgentModelOverride(id, modelInput) {
+  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))
+  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]
+  await writeStore(BUILTIN_OVERRIDES_STORE, next)
+  return { ...current, model: modelReferenceSnapshot(model) }
 }
 
 export async function deleteCustomAgentProfile(id) {
-  await atomicUpdate(STORE, (data) => {
-    const map = data && typeof data === 'object' ? data : {}
-    if (!map[id]) throw requestError('Agent not found', 404)
-    delete map[id]
-    return map
-  })
+  await ensureCustomAgentStoreMigrated()
+  const current = await getAgentProfile(id)
+  assertEditableUserProfile(current)
+  await deleteUserAgentProfileMarkdown(current)
 }
 
 export function agentProfileSnapshot(profile) {
@@ -214,6 +337,11 @@ export function agentProfileSnapshot(profile) {
     description: profile.description,
     systemPrompt: profile.systemPrompt,
     allowedTools: [...profile.allowedTools],
+    capabilityPolicy: profile.capabilityPolicy || inferCapabilityPolicy(profile.allowedTools || []),
+    model: modelReferenceSnapshot(profile.model),
+    thinkingLevel: normalizeAgentProfileThinkingLevel(profile.thinkingLevel),
+    lifecycle: profile.lifecycle || (profile.builtin ? 'builtin' : 'persistent'),
+    managed: profile.managed === true,
     maxRuntimeMs: profile.maxRuntimeMs,
     maxToolCalls: profile.maxToolCalls,
     enabledAsSubagent: profile.enabledAsSubagent === true,
@@ -222,9 +350,12 @@ export function agentProfileSnapshot(profile) {
     readonly: profile.readonly === true || profile.builtin === true,
     filePath: profile.filePath,
     relativePath: profile.relativePath,
+    warnings: Array.isArray(profile.warnings) ? [...profile.warnings] : undefined,
   }
 }
 
+export { AGENT_PROFILE_TOOL_NAMES } from './agent-profile-schema.mjs'
+
 export function listAvailableAgentTools() {
   const labels = {
     read_file: 'Read file',

package/server/ai-http-logger.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { randomUUID } from 'node:crypto'
-import { streamSimple } from '@earendil-works/pi-ai'
+import { streamSimple } from '@earendil-works/pi-ai/compat'
 import { logsDir } from './storage.mjs'
 
 const PATCH_MARKER = Symbol.for('quickforge.aiHttpLogger.fetchPatched')

package/server/auto-compaction.mjs

@@ -5,7 +5,7 @@ import { estimateContextUsage, shouldCompactContextByPercent } from './context-u
 export const AUTO_COMPACT_SETTINGS_KEY = 'auto-compact-settings'
 
 export const DEFAULT_AUTO_COMPACT_SETTINGS = {
-  enabled: false,
+  enabled: true,
   thresholdPercent: 80,
   keepRecentTurns: 2,
   minSourceChars: 1600,
@@ -24,7 +24,7 @@ function clampNumber(value, fallback, min, max) {
 export function normalizeAutoCompactSettings(value) {
   if (!value || typeof value !== 'object') return { ...DEFAULT_AUTO_COMPACT_SETTINGS }
   return {
-    enabled: value.enabled === true,
+    enabled: value.enabled !== false,
     thresholdPercent: clampNumber(value.thresholdPercent, DEFAULT_AUTO_COMPACT_SETTINGS.thresholdPercent, 50, 95),
     keepRecentTurns: clampNumber(value.keepRecentTurns, DEFAULT_AUTO_COMPACT_SETTINGS.keepRecentTurns, 1, 20),
     minSourceChars: clampNumber(value.minSourceChars, DEFAULT_AUTO_COMPACT_SETTINGS.minSourceChars, 0, 200000),

package/server/project-route-context.mjs

@@ -0,0 +1,25 @@
+import path from 'node:path'
+
+export function resolveRequestedProject(config, projectId, defaultWorkspaceRoot) {
+  if (!projectId) return config.projects.find((project) => project.id === config.activeProjectId) ?? config.projects[0]
+  if (projectId === 'default') {
+    return {
+      id: 'default',
+      name: 'workspace',
+      path: defaultWorkspaceRoot,
+      lastOpenedAt: '',
+      sortOrder: 0,
+      skills: [],
+      commandDir: '',
+    }
+  }
+  const project = config.projects.find((item) => item.id === projectId)
+  if (project) return project
+  const error = new Error('Unknown project')
+  error.statusCode = 404
+  throw error
+}
+
+export function workspaceRootAfterProjectDeletion(activeProject, defaultWorkspaceRoot) {
+  return path.resolve(activeProject?.path || defaultWorkspaceRoot)
+}

package/server/routes/agent-profiles.mjs

@@ -1,4 +1,4 @@
-import { streamSimple } from '@earendil-works/pi-ai'
+import { streamSimple } from '@earendil-works/pi-ai/compat'
 import { sendJson, readJsonBody, decodeSegment } from '../utils/response.mjs'
 import { readStore } from '../storage.mjs'
 import { logger } from '../utils/logger.mjs'
@@ -9,6 +9,7 @@ import {
   getAgentProfile,
   listAgentProfiles,
   listAvailableAgentTools,
+  updateBuiltinAgentModelOverride,
   updateCustomAgentProfile,
 } from '../agent-profiles.mjs'
 
@@ -155,9 +156,14 @@ export async function handleAgentProfilesApi(req, res, url) {
 
     if (req.method === 'PATCH' || req.method === 'PUT') {
       const current = await getAgentProfile(id)
-      if (current?.builtin) throw requestError('Built-in agents cannot be modified', 403)
-      if (current?.readonly) throw requestError('File-based agents cannot be modified from the API', 403)
       const body = await readJsonBody(req)
+      if (current?.builtin) {
+        const keys = Object.keys(body || {})
+        if (keys.length !== 1 || keys[0] !== 'model') throw requestError('Built-in agents only allow model updates', 403)
+        sendJson(res, 200, { agent: agentProfileSnapshot(await updateBuiltinAgentModelOverride(id, body.model)) })
+        return
+      }
+      if (current?.readonly) throw requestError('Read-only agents cannot be modified from the API', 403)
       sendJson(res, 200, { agent: await updateCustomAgentProfile(id, body || {}) })
       return
     }
@@ -165,7 +171,7 @@ export async function handleAgentProfilesApi(req, res, url) {
     if (req.method === 'DELETE') {
       const current = await getAgentProfile(id)
       if (current?.builtin) throw requestError('Built-in agents cannot be deleted', 403)
-      if (current?.readonly) throw requestError('File-based agents cannot be deleted from the API', 403)
+      if (current?.readonly) throw requestError('Read-only agents cannot be deleted from the API', 403)
       await deleteCustomAgentProfile(id)
       sendJson(res, 200, { ok: true })
       return

package/server/routes/models.mjs

@@ -1,4 +1,4 @@
-import { streamSimple } from '@earendil-works/pi-ai'
+import { streamSimple } from '@earendil-works/pi-ai/compat'
 import { sendJson, readJsonBody } from '../utils/response.mjs'
 import { readStore } from '../storage.mjs'
 import { logger } from '../utils/logger.mjs'

package/server/routes/project.mjs

@@ -1,6 +1,7 @@
 import { sendJson, readJsonBody, decodeSegment } from '../utils/response.mjs'
 import { logger } from '../utils/logger.mjs'
 import { getActiveProject, setActiveProjectPath, readProjectConfig, getDefaultWorkspaceRoot } from '../project-config.mjs'
+import { resolveRequestedProject, workspaceRootAfterProjectDeletion } from '../project-route-context.mjs'
 import { listProjectCommands, createCommandFile } from '../custom-commands.mjs'
 import { atomicProjectConfigUpdate } from '../storage.mjs'
 import { getWorkspaceRoot, setWorkspaceRoot } from '../utils/workspace.mjs'
@@ -137,13 +138,12 @@ export async function handleProjectApi(req, res, url) {
 
   if (req.method === 'POST' && url.pathname === '/api/project/open-path') {
     const body = await readJsonBody(req)
-    const active = body?.projectId
-      ? config.projects.find((project) => project.id === body.projectId) ?? getActiveProject(config)
-      : getActiveProject(config)
+    const active = resolveRequestedProject(config, body?.projectId, getDefaultWorkspaceRoot())
     const target = String(body?.path || '')
+    const root = active?.path || getWorkspaceRoot() || getDefaultWorkspaceRoot()
     const resolved = target && path.isAbsolute(target)
       ? path.resolve(target)
-      : path.resolve(active?.path || '', target)
+      : path.resolve(root, target)
     await openPathInFileManager(resolved)
     sendJson(res, 200, { ok: true })
     return
@@ -151,9 +151,7 @@ export async function handleProjectApi(req, res, url) {
 
   if (req.method === 'POST' && url.pathname === '/api/project/command') {
     const body = await readJsonBody(req)
-    const active = body?.projectId
-      ? config.projects.find((project) => project.id === body.projectId) ?? getActiveProject(config)
-      : getActiveProject(config)
+    const active = resolveRequestedProject(config, body?.projectId, getDefaultWorkspaceRoot())
     if (!active?.path) {
       const error = new Error('No active project')
       error.statusCode = 400
@@ -178,9 +176,7 @@ export async function handleProjectApi(req, res, url) {
       return cfg
     })
     const active = getActiveProject(updated)
-    if (active?.path) {
-      setWorkspaceRoot(path.resolve(active.path))
-    }
+    setWorkspaceRoot(workspaceRootAfterProjectDeletion(active, getDefaultWorkspaceRoot()))
     sendJson(res, 200, { project: active ?? null, projects: updated.projects, workspaceRoot: getWorkspaceRoot() })
     return
   }

package/server/routes/scheduled-tasks.mjs

@@ -1,4 +1,4 @@
-import { streamSimple } from '@earendil-works/pi-ai'
+import { streamSimple } from '@earendil-works/pi-ai/compat'
 import { readJsonBody, sendJson, decodeSegment } from '../utils/response.mjs'
 import { readStore, atomicUpdate } from '../storage.mjs'
 import { createAgent, getSessionEventBus, agentEvents, persistSessionState } from '../agent-manager.mjs'