Apply npm-app changes from brandon/base-lite branch

Adds agent resolution logic and updates CLI handlers:
- New agent resolution files (resolve.ts and resolve.test.ts)
- Updates to CLI handlers for agents, publishing, and subagent management
- New traces handler file
- Modifications to main CLI and client files

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

npm-app/src/agents/resolve.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'bun:test'
+import { DEFAULT_ORG_PREFIX } from '@codebuff/common/util/agent-name-normalization'
+import { resolveCliAgentId } from './resolve'
+
+describe('resolveCliAgentId', () => {
+  it('returns undefined when input is undefined', () => {
+    expect(resolveCliAgentId(undefined, [])).toBeUndefined()
+  })
+
+  it('preserves explicitly prefixed identifiers', () => {
+    expect(resolveCliAgentId('publisher/name', [])).toBe('publisher/name')
+    expect(resolveCliAgentId(`${DEFAULT_ORG_PREFIX}foo@1.2.3`, [])).toBe(
+      `${DEFAULT_ORG_PREFIX}foo@1.2.3`,
+    )
+  })
+  it('returns input as-is when it exists locally', () => {
+    expect(resolveCliAgentId('local-agent', ['local-agent'])).toBe(
+      'local-agent',
+    )
+  })
+
+  it('prefixes unknown, unprefixed ids with DEFAULT_ORG_PREFIX', () => {
+    expect(resolveCliAgentId('unknown', [])).toBe(
+      `${DEFAULT_ORG_PREFIX}unknown`,
+    )
+  })
+})

npm-app/src/agents/resolve.ts

@@ -0,0 +1,17 @@
+import { DEFAULT_ORG_PREFIX } from '@codebuff/common/util/agent-name-normalization'
+
+export function resolveCliAgentId(
+  input: string | undefined,
+  localAgentIds: string[],
+): string | undefined {
+  if (!input) return input
+
+  // Preserve explicitly prefixed identifiers like publisher/name
+  if (input.includes('/')) return input
+
+  // If it exists locally, use as-is
+  if (localAgentIds.includes(input)) return input
+
+  // Otherwise default to <DEFAULT_ORG_PREFIX><name>
+  return `${DEFAULT_ORG_PREFIX}${input}`
+}

npm-app/src/cli-handlers/agents.ts

@@ -19,7 +19,11 @@ import intermediateGitCommitter from '../../../common/src/templates/initial-agen
 import advancedFileExplorer from '../../../common/src/templates/initial-agents-dir/examples/03-advanced-file-explorer' with { type: 'text' }
 import myCustomAgent from '../../../common/src/templates/initial-agents-dir/my-custom-agent' with { type: 'text' }
 
-import { loadLocalAgents, getLoadedAgentNames } from '../agents/load-agents'
+import {
+  loadLocalAgents,
+  getLoadedAgentNames,
+  loadedAgents,
+} from '../agents/load-agents'
 import { CLI } from '../cli'
 import { getProjectRoot } from '../project-files'
 import { Spinner } from '../utils/spinner'
@@ -90,35 +94,87 @@ export async function enterAgentsBuffer(rl: any, onExit: () => void) {
     customAgentFiles = filterCustomAgentFiles(files)
   }
 
-  // Add agents section header
-  actions.push({
-    id: '__agents_header__',
-    name:
-      bold(cyan('Custom Agents')) +
-      gray(` • ${customAgentFiles.length} in ${AGENT_TEMPLATES_DIR}`),
-    description: '',
-    isBuiltIn: false,
-    isSectionHeader: true,
-  })
-
   // Build agent list starting with management actions
   agentList = [...actions]
 
-  // Add custom agents from .agents/templates
-  if (customAgentFiles.length > 0) {
-    for (const file of customAgentFiles) {
-      const agentId = extractAgentIdFromFileName(file)
-      const agentName = localAgents[agentId] || agentId
+  // Collect custom agents from .agents/templates
+  const agentEntries = customAgentFiles.map((file) => {
+    const agentId = extractAgentIdFromFileName(file)
+    const filePath = path.join(agentsDir, file)
+    let mtime = 0
+    try {
+      mtime = fs.statSync(filePath).mtimeMs
+    } catch {}
+    const def = (loadedAgents as any)[agentId]
+    return { file, agentId, filePath, mtime, def }
+  })
+
+  const validAgents = agentEntries
+    .filter((e) => e.def && e.def.id && e.def.model)
+    .sort((a, b) => b.mtime - a.mtime)
+
+  const now = Date.now()
+  const sevenDaysMs = 7 * 24 * 60 * 60 * 1000
+  const recentAgents = validAgents.filter((e) => now - e.mtime <= sevenDaysMs)
+  const otherAgents = validAgents.filter((e) => now - e.mtime > sevenDaysMs)
+
+  if (validAgents.length > 0) {
+    if (recentAgents.length > 0) {
+      agentList.push({
+        id: '__recent_agents_header__',
+        name: bold(cyan('Recently Updated')) + gray(' • last 7 days'),
+        description: '',
+        isBuiltIn: false,
+        isSectionHeader: true,
+      })
+
+      for (const entry of recentAgents) {
+        const agentName =
+          localAgents[entry.agentId] || entry.def?.displayName || entry.agentId
+        agentList.push({
+          id: entry.agentId,
+          name: agentName,
+          description: entry.def?.description || 'Custom user-defined agent',
+          isBuiltIn: false,
+          filePath: entry.filePath,
+        })
+      }
+    }
+
+    if (otherAgents.length > 0) {
       agentList.push({
-        id: agentId,
-        name: agentName,
-        description: 'Custom user-defined agent',
+        id: '__agents_header__',
+        name:
+          bold(cyan('Custom Agents')) +
+          gray(` • ${otherAgents.length} in ${AGENT_TEMPLATES_DIR}`),
+        description: '',
         isBuiltIn: false,
-        filePath: path.join(agentsDir, file),
+        isSectionHeader: true,
       })
+
+      for (const entry of otherAgents) {
+        const agentName =
+          localAgents[entry.agentId] || entry.def?.displayName || entry.agentId
+        agentList.push({
+          id: entry.agentId,
+          name: agentName,
+          description: entry.def?.description || 'Custom user-defined agent',
+          isBuiltIn: false,
+          filePath: entry.filePath,
+        })
+      }
     }
   } else {
-    // If no custom agents, add a helpful message
+    // No valid agents; show header + placeholder
+    agentList.push({
+      id: '__agents_header__',
+      name:
+        bold(cyan('Custom Agents')) +
+        gray(` • ${customAgentFiles.length} in ${AGENT_TEMPLATES_DIR}`),
+      description: '',
+      isBuiltIn: false,
+      isSectionHeader: true,
+    })
     agentList.push({
       id: '__no_agents__',
       name: gray('No custom agents found'),
@@ -128,8 +184,6 @@ export async function enterAgentsBuffer(rl: any, onExit: () => void) {
     })
   }
 
-  // No need for special handling here since we now have a proper placeholder
-
   // Initialize selection to first selectable item
   selectedIndex = 0
   // Find first selectable item (skip section headers, separators, placeholders)
@@ -400,7 +454,7 @@ function renderAgentsList() {
   }
 
   // Display status line at bottom
-  const statusLine = `\n${gray(`Use ↑/↓/j/k to navigate, Enter to select, ESC to go back`)}`
+  const statusLine = `\n${gray(`Use ↑/↓/j/k to navigate, Enter to select, ESC or q to go back`)}`
 
   process.stdout.write(statusLine)
   process.stdout.write(HIDE_CURSOR)
@@ -416,7 +470,11 @@ function setupAgentsKeyHandler(rl: any, onExit: () => void) {
 
   // Add our custom handler
   process.stdin.on('keypress', (str: string, key: any) => {
-    if (key && key.name === 'escape') {
+    // Support ESC or 'q' (no ctrl/meta) to go back
+    if (
+      (key && key.name === 'escape') ||
+      (!key?.ctrl && !key?.meta && str === 'q')
+    ) {
       exitAgentsBuffer(rl)
       onExit()
       return

npm-app/src/cli-handlers/publish.ts

@@ -12,6 +12,7 @@ import type {
   PublishAgentsResponse,
 } from '@codebuff/common/types/api/agents/publish'
 import type { DynamicAgentTemplate } from '@codebuff/common/types/dynamic-agent-template'
+import { pluralize } from '@codebuff/common/util/string'
 
 /**
  * Handle the publish command to upload agent templates to the backend
@@ -105,7 +106,9 @@ import type { DynamicAgentTemplate } from '@codebuff/common/types/dynamic-agent-
         return
       }
 
-      console.log(red(`❌ Failed to publish agents: ${result.error}`))
+      console.log(red(`❌ Failed to publish your agents`))
+      if (result.details) console.log(red(`\n${result.details}`))
+      if (result.hint) console.log(yellow(`\nHint: ${result.hint}`))
 
       // Show helpful guidance based on error type
       if (result.error?.includes('Publisher field required')) {
@@ -179,31 +182,13 @@ async function publishAgentTemplates(
 
     if (!response.ok) {
       result = result as PublishAgentsErrorResponse
-      // Extract detailed error information from the response
-      let errorMessage =
-        result.error || `HTTP ${response.status}: ${response.statusText}`
-
-      // If there are validation details, include them
-      if (result.details) {
-        errorMessage += `\n\nDetails: ${result.details}`
-      }
-
-      // If there are specific validation errors, format them nicely
-      if (result.validationErrors && Array.isArray(result.validationErrors)) {
-        const formattedErrors = result.validationErrors
-          .map((err: any) => {
-            const path =
-              err.path && err.path.length > 0 ? `${err.path.join('.')}: ` : ''
-            return `  • ${path}${err.message}`
-          })
-          .join('\n')
-        errorMessage += `\n\nValidation errors:\n${formattedErrors}`
-      }
-
+      // Build clean error object without duplicating details into the error string
       return {
         success: false,
-        error: errorMessage,
+        error:
+          result.error || `HTTP ${response.status}: ${response.statusText}`,
         details: result.details,
+        hint: result.hint,
         statusCode: response.status,
         availablePublishers: result.availablePublishers,
         validationErrors: result.validationErrors,
@@ -214,18 +199,31 @@ async function publishAgentTemplates(
       ...result,
       statusCode: response.status,
     }
-  } catch (error) {
+  } catch (err: any) {
     // Handle network errors, timeouts, etc.
-    if (error instanceof TypeError && error.message.includes('fetch')) {
+    if (err instanceof TypeError && err.message.includes('fetch')) {
       return {
         success: false,
         error: `Network error: Unable to connect to ${websiteUrl}. Please check your internet connection and try again.`,
       }
     }
 
+    const body = err?.responseBody || err?.body || err
+    const error = body?.error || body?.message || 'Failed to publish'
+    const details = body?.details
+    const hint = body?.hint
+
+    // Log for visibility
+    console.error(`❌ Failed to publish: ${error}`)
+    if (details) console.error(`\nDetails: ${details}`)
+    if (hint) console.error(`\nHint: ${hint}`)
+
+    // Return a valid error object so callers can display the hint
     return {
       success: false,
-      error: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
-    }
+      error,
+      details,
+      hint,
+    } as PublishAgentsResponse
   }
 }

npm-app/src/cli-handlers/subagent-list.ts

@@ -2,7 +2,7 @@ import { pluralize } from '@codebuff/common/util/string'
 import { green, yellow, cyan, magenta, bold, gray } from 'picocolors'
 
 import { getSubagentsChronological } from '../subagent-storage'
-import { enterSubagentBuffer } from './subagent'
+import { enterSubagentBuffer } from './traces'
 import {
   ENTER_ALT_BUFFER,
   EXIT_ALT_BUFFER,
@@ -329,7 +329,8 @@ function renderSubagentList() {
   }
 
   // Display status line at bottom
-  const statusLine = `\n${gray(`Use ↑/↓/j/k to navigate, PgUp/PgDn for fast scroll, Enter to view, ESC to go back`)}`
+  // Update: mention ESC or q
+  const statusLine = `\n${gray(`Use ↑/↓/j/k to navigate, PgUp/PgDn for fast scroll, Enter to view, ESC or q to go back`)}`
 
   process.stdout.write(statusLine)
   process.stdout.write(HIDE_CURSOR)
@@ -345,7 +346,11 @@ function setupSubagentListKeyHandler(rl: any, onExit: () => void) {
 
   // Add our custom handler
   process.stdin.on('keypress', (str: string, key: any) => {
-    if (key && key.name === 'escape') {
+    // Support ESC or 'q' (no ctrl/meta) to go back
+    if (
+      (key && key.name === 'escape') ||
+      (!key?.ctrl && !key?.meta && str === 'q')
+    ) {
       exitSubagentListBuffer(rl)
       onExit()
       return