feat(imports): add namespacing support for imported resources

- Add new registry functions for import metadata lookup
- Implement namespacing for agents, workflows, and placeholders
- Support both raw and namespaced IDs in agent resolution
- Cache configs and add debug logging for troubleshooting

Author: moazbuilds

src/agents/runner/config.ts

@@ -3,7 +3,7 @@ import * as path from 'node:path';
 
 import { collectAgentDefinitions, resolveProjectRoot } from '../../shared/agents/index.js';
 import type { AgentDefinition } from '../../shared/agents/config/types.js';
-import { resolvePromptPath } from '../../shared/imports/index.js';
+import { resolvePromptPath, getAllInstalledImports } from '../../shared/imports/index.js';
 import { resolvePackageRoot } from '../../shared/runtime/root.js';
 
 const packageRoot = resolvePackageRoot(import.meta.url, 'agent runner config');
@@ -34,6 +34,7 @@ function getDefaultPromptPath(agentId: string): string {
 
 /**
  * Loads the agent configuration by ID from all available agent files
+ * Supports both raw IDs and namespaced IDs (e.g., 'bmad-pm' or 'bmad:bmad-pm')
  */
 export async function loadAgentConfig(agentId: string, projectRoot?: string): Promise<AgentConfig> {
   const lookupBase = projectRoot ?? process.env.CODEMACHINE_CWD ?? process.cwd();
@@ -42,7 +43,23 @@ export async function loadAgentConfig(agentId: string, projectRoot?: string): Pr
   // Collect all agent definitions from all config files
   const agents = await collectAgentDefinitions(resolvedRoot);
 
-  const config = agents.find((a) => a.id === agentId) as AgentConfig | undefined;
+  // Try direct lookup first
+  let config = agents.find((a) => a.id === agentId) as AgentConfig | undefined;
+
+  // If not found, try looking up with import namespaces prefixed
+  // This handles cases where workflow templates reference agents by raw ID
+  // but agents are registered with namespace (e.g., 'bmad-pm' -> 'bmad:bmad-pm')
+  if (!config) {
+    const imports = getAllInstalledImports();
+    for (const imp of imports) {
+      const namespacedId = `${imp.name}:${agentId}`;
+      config = agents.find((a) => a.id === namespacedId) as AgentConfig | undefined;
+      if (config) {
+        break;
+      }
+    }
+  }
+
   if (!config) {
     throw new Error(`Unknown agent id: ${agentId}. Available agents: ${agents.map(a => a.id).join(', ')}`);
   }

src/cli/tui/shared/config/agent-characters.ts

@@ -12,6 +12,7 @@ import * as path from "node:path"
 import { existsSync, readFileSync } from "node:fs"
 import { resolvePackageRoot } from "../../../../shared/runtime/root.js"
 import { getAllInstalledImports } from "../../../../shared/imports/registry.js"
+import { debug } from "../../../../shared/logging/logger.js"
 import type { ActivityType, AgentCharactersConfig, Persona } from "./agent-characters.types.js"
 
 let cachedConfig: AgentCharactersConfig | null = null
@@ -30,14 +31,44 @@ function getPackageRoot(): string | null {
 /**
  * Merges two agent characters configs
  * Imported config extends/overrides the base config
+ * @param packageName - If provided, namespace agent IDs with this package name
  */
 function mergeCharactersConfigs(
   base: AgentCharactersConfig,
-  imported: AgentCharactersConfig
+  imported: Partial<AgentCharactersConfig>,
+  packageName?: string
 ): AgentCharactersConfig {
+  // Namespace agent IDs if from an imported package
+  const namespacedAgents: Record<string, string> = {}
+  if (imported.agents) {
+    for (const [agentId, personaName] of Object.entries(imported.agents)) {
+      const namespacedId = packageName ? `${packageName}:${agentId}` : agentId
+      namespacedAgents[namespacedId] = personaName
+    }
+  }
+
+  // Namespace persona names if from an imported package
+  const namespacedPersonas: Record<string, Persona> = {}
+  if (imported.personas) {
+    for (const [personaName, persona] of Object.entries(imported.personas)) {
+      const namespacedName = packageName ? `${packageName}:${personaName}` : personaName
+      namespacedPersonas[namespacedName] = persona
+    }
+  }
+
+  // Update agent mappings to use namespaced persona names
+  const finalAgents: Record<string, string> = { ...base.agents }
+  for (const [agentId, personaName] of Object.entries(namespacedAgents)) {
+    // If persona was namespaced AND the persona exists in imported, update the mapping
+    // Otherwise keep the original persona name (allows referencing base personas)
+    const namespacedPersonaName = packageName ? `${packageName}:${personaName}` : personaName
+    const finalPersonaName = imported.personas?.[personaName] ? namespacedPersonaName : personaName
+    finalAgents[agentId] = finalPersonaName
+  }
+
   return {
-    personas: { ...base.personas, ...imported.personas },
-    agents: { ...base.agents, ...imported.agents },
+    personas: { ...base.personas, ...namespacedPersonas },
+    agents: finalAgents,
     defaultPersona: base.defaultPersona, // Keep base default
   }
 }
@@ -47,13 +78,17 @@ function mergeCharactersConfigs(
  */
 function loadCharactersFromPath(configPath: string): AgentCharactersConfig | null {
   if (!existsSync(configPath)) {
+    debug('[Characters] loadCharactersFromPath: file does not exist: %s', configPath)
     return null
   }
 
   try {
     const content = readFileSync(configPath, "utf-8")
-    return JSON.parse(content) as AgentCharactersConfig
-  } catch {
+    const parsed = JSON.parse(content) as AgentCharactersConfig
+    debug('[Characters] loadCharactersFromPath: successfully loaded %s', configPath)
+    return parsed
+  } catch (err) {
+    debug('[Characters] loadCharactersFromPath: parse error for %s: %s', configPath, err)
     return null
   }
 }
@@ -68,6 +103,8 @@ export function loadAgentCharactersConfig(): AgentCharactersConfig {
     return cachedConfig
   }
 
+  debug('[Characters] loadAgentCharactersConfig: loading fresh config...')
+
   // Start with default config
   let config = getDefaultConfig()
 
@@ -78,22 +115,47 @@ export function loadAgentCharactersConfig(): AgentCharactersConfig {
     const baseConfig = loadCharactersFromPath(basePath)
     if (baseConfig) {
       config = baseConfig
+      debug('[Characters] Loaded base config from %s, personas=%o, agents=%o, default=%s',
+        basePath, Object.keys(config.personas), Object.keys(config.agents), config.defaultPersona)
     }
   }
 
-  // Merge characters from all installed imports
+  // Merge characters from all installed imports with namespacing
   try {
     const imports = getAllInstalledImports()
+    debug('[Characters] Found %d imports to merge', imports.length)
     for (const imp of imports) {
-      const importedConfig = loadCharactersFromPath(imp.resolvedPaths.characters)
-      if (importedConfig) {
-        config = mergeCharactersConfigs(config, importedConfig)
+      try {
+        const charactersPath = imp.resolvedPaths?.characters
+        debug('[Characters] Import %s: charactersPath=%s, exists=%s',
+          imp.name, charactersPath, charactersPath ? existsSync(charactersPath) : 'no-path')
+        if (!charactersPath) {
+          debug('[Characters] Import %s has no characters path, skipping', imp.name)
+          continue
+        }
+        const importedConfig = loadCharactersFromPath(charactersPath)
+        if (importedConfig) {
+          debug('[Characters] Merging import %s: personas=%o, agents=%o',
+            imp.name,
+            importedConfig.personas ? Object.keys(importedConfig.personas) : [],
+            importedConfig.agents ? Object.keys(importedConfig.agents) : [])
+          // Namespace agent IDs and persona names with the import package name
+          config = mergeCharactersConfigs(config, importedConfig, imp.name)
+        } else {
+          debug('[Characters] Import %s: failed to load config from %s', imp.name, charactersPath)
+        }
+      } catch (importErr) {
+        // Log error for this specific import but continue with others
+        debug('[Characters] Error processing import %s: %s', imp.name, importErr)
       }
     }
-  } catch {
-    // Silently ignore import errors - may not have imports system initialized
+  } catch (err) {
+    debug('[Characters] Error loading imports registry: %s', err)
   }
 
+  debug('[Characters] Final config: personas=%o, agents=%o, default=%s',
+    Object.keys(config.personas), Object.keys(config.agents), config.defaultPersona)
+
   cachedConfig = config
   return cachedConfig
 }
@@ -124,14 +186,55 @@ function getDefaultConfig(): AgentCharactersConfig {
   }
 }
 
+/**
+ * Resolve agent ID to find matching character config
+ * Handles workflow agent IDs with step suffixes (e.g., "bmad-analyst-step-0")
+ * and finds namespaced agents (e.g., "bmad:bmad-analyst")
+ */
+function resolveAgentId(agentId: string, agents: Record<string, string>): string | null {
+  debug('[Characters] resolveAgentId: input=%s, available agents=%o', agentId, Object.keys(agents))
+
+  // 1. Try exact match first
+  if (agents[agentId]) {
+    debug('[Characters] resolveAgentId: exact match found for %s', agentId)
+    return agentId
+  }
+
+  // 2. Strip -step-N suffix and try again (workflow agent IDs)
+  const baseId = agentId.replace(/-step-\d+$/, '')
+  debug('[Characters] resolveAgentId: baseId (stripped suffix)=%s', baseId)
+
+  if (baseId !== agentId && agents[baseId]) {
+    debug('[Characters] resolveAgentId: match found for baseId %s', baseId)
+    return baseId
+  }
+
+  // 3. Look for namespaced version (e.g., "bmad:bmad-analyst" for "bmad-analyst")
+  for (const key of Object.keys(agents)) {
+    // Check if key ends with ":baseId" (namespaced match)
+    if (key.endsWith(`:${baseId}`)) {
+      debug('[Characters] resolveAgentId: namespaced match found %s for baseId %s', key, baseId)
+      return key
+    }
+  }
+
+  debug('[Characters] resolveAgentId: no match found for %s, will use default', agentId)
+  return null
+}
+
 /**
  * Gets the persona configuration for a specific agent
  * Looks up agent -> persona mapping, falls back to defaultPersona
+ * Handles workflow agent IDs with step suffixes and namespaced imports
  */
 export function getCharacter(agentId: string): Persona {
   const config = loadAgentCharactersConfig()
-  const personaName = config.agents[agentId] ?? config.defaultPersona
-  return config.personas[personaName] ?? config.personas[config.defaultPersona] ?? getDefaultConfig().personas.default
+  const resolvedId = resolveAgentId(agentId, config.agents)
+  const personaName = resolvedId ? config.agents[resolvedId] : config.defaultPersona
+  const persona = config.personas[personaName] ?? config.personas[config.defaultPersona] ?? getDefaultConfig().personas.default
+  debug('[Characters] getCharacter: agentId=%s → resolvedId=%s → persona=%s → face=%s',
+    agentId, resolvedId ?? 'null', personaName, persona.baseFace)
+  return persona
 }
 
 /**

src/runtime/services/workspace/discovery.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 
 import { collectAgentsFromWorkflows } from '../../../shared/agents/index.js';
 import { resolvePackageRoot } from '../../../shared/runtime/root.js';
+import { getImportRootsWithMetadata } from '../../../shared/imports/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -40,29 +41,52 @@ export function debugLog(...args: unknown[]): void {
 export type AgentDefinition = Record<string, unknown> & { mirrorPath?: string };
 export type LoadedAgent = AgentDefinition & { id: string; source?: 'main' | 'sub' | 'legacy' | 'workflow' };
 
+/**
+ * Module candidate with metadata for namespacing
+ */
+interface ModuleCandidate {
+  source: 'main' | 'sub' | 'legacy';
+  packageName: string | null;
+}
+
 export async function loadAgents(
   candidateRoots: string[],
   filterIds?: string[]
 ): Promise<{ allAgents: AgentDefinition[]; subAgents: AgentDefinition[] }> {
-  const candidateModules = new Map<string, 'main' | 'sub' | 'legacy'>();
+  // Build a map from import path to package name for namespacing
+  const importedRootsWithMeta = getImportRootsWithMetadata();
+  const importPathToPackage = new Map<string, string>();
+  for (const imp of importedRootsWithMeta) {
+    importPathToPackage.set(path.resolve(imp.path), imp.packageName);
+  }
+
+  const candidateModules = new Map<string, ModuleCandidate>();
 
   for (const root of candidateRoots) {
     if (!root) continue;
     const resolvedRoot = path.resolve(root);
+
+    // Determine if this root is from an import
+    const packageName = importPathToPackage.get(resolvedRoot) ?? null;
+
     for (const filename of AGENT_MODULE_FILENAMES) {
       const moduleCandidate = path.join(resolvedRoot, 'config', filename);
       const distCandidate = path.join(resolvedRoot, 'dist', 'config', filename);
 
-      const tag = filename === 'main.agents.js' ? 'main' : filename === 'sub.agents.js' ? 'sub' : 'legacy';
+      const source = filename === 'main.agents.js' ? 'main' : filename === 'sub.agents.js' ? 'sub' : 'legacy';
 
-      if (existsSync(moduleCandidate)) candidateModules.set(moduleCandidate, tag);
-      if (existsSync(distCandidate)) candidateModules.set(distCandidate, tag);
+      if (existsSync(moduleCandidate)) {
+        candidateModules.set(moduleCandidate, { source, packageName });
+      }
+      if (existsSync(distCandidate)) {
+        candidateModules.set(distCandidate, { source, packageName });
+      }
     }
   }
 
   const byId = new Map<string, LoadedAgent>();
 
-  for (const [modulePath, source] of candidateModules.entries()) {
+  for (const [modulePath, { source, packageName }] of candidateModules.entries()) {
     try {
       delete require.cache[require.resolve(modulePath)];
     } catch {
@@ -76,10 +100,14 @@ export async function loadAgents(
       if (!agent || typeof agent.id !== 'string') {
         continue;
       }
-      const id = agent.id.trim();
-      if (!id) {
+      const rawId = agent.id.trim();
+      if (!rawId) {
         continue;
       }
+
+      // Namespace the ID if from an imported package
+      const id = packageName ? `${packageName}:${rawId}` : rawId;
+
       const existing = byId.get(id);
       const sourceTag = existing?.source ?? source;
       const merged: LoadedAgent = {
@@ -92,7 +120,8 @@ export async function loadAgents(
     }
   }
 
-  const workflowAgents = await collectAgentsFromWorkflows(candidateRoots);
+  // Pass import path map for workflow agent namespacing
+  const workflowAgents = await collectAgentsFromWorkflows(candidateRoots, importPathToPackage);
   for (const agent of workflowAgents) {
     if (!agent || typeof agent.id !== 'string') continue;
     const id = agent.id.trim();
@@ -111,6 +140,7 @@ export async function loadAgents(
   const allAgents = Array.from(byId.values()).map(({ source: _source, ...agent }) => ({ ...agent }));
 
   // Filter sub-agents by IDs if filterIds is provided
+  // Note: filterIds should use namespaced IDs for imported agents
   const subAgents = Array.from(byId.values())
     .filter((agent) => {
       if (agent.source !== 'sub') return false;