feat(imports): add import-aware path resolution utilities

Implement new resolution functions that check imported packages before local paths. This enables better sharing of resources across projects while maintaining backwards compatibility. The changes include:
- New resolve.js module with path resolution utilities
- Updates to prompt, workflow and agent loading to use imports first
- Clearer error messages when resources aren't found
- Improved debug logging for resolution paths

Author: moazbuilds

src/agents/runner/chained.ts

@@ -3,6 +3,10 @@ import * as path from 'node:path';
 
 import { debug } from '../../shared/logging/logger.js';
 import type { ChainedPathEntry, ConditionalChainedPath } from '../../shared/agents/config/types.js';
+import { resolvePathWithImports } from '../../shared/imports/index.js';
+import { resolvePackageRoot } from '../../shared/runtime/root.js';
+
+const packageRoot = resolvePackageRoot(import.meta.url, 'chained prompts');
 
 /**
  * Represents a chained prompt loaded from a .md file
@@ -89,14 +93,20 @@ function filenameToName(filename: string): string {
 
 /**
  * Load a single chained prompt from a file
+ * Checks imported packages first, then project root
  */
 async function loadPromptFromFile(
   filePath: string,
   projectRoot: string
 ): Promise<ChainedPrompt | null> {
-  const absolutePath = path.isAbsolute(filePath)
-    ? filePath
-    : path.resolve(projectRoot, filePath);
+  let absolutePath: string;
+  if (path.isAbsolute(filePath)) {
+    absolutePath = filePath;
+  } else {
+    // Try to resolve from imports first, then fall back to project root
+    const importResolved = resolvePathWithImports(filePath, packageRoot, [projectRoot]);
+    absolutePath = importResolved ?? path.resolve(projectRoot, filePath);
+  }
 
   try {
     const rawContent = await fs.readFile(absolutePath, 'utf-8');
@@ -117,15 +127,20 @@ async function loadPromptFromFile(
 
 /**
  * Load chained prompts from a single folder
+ * Checks imported packages first, then project root
  */
 async function loadPromptsFromFolder(
   folderPath: string,
   projectRoot: string
 ): Promise<ChainedPrompt[]> {
-  // Resolve path
-  const absolutePath = path.isAbsolute(folderPath)
-    ? folderPath
-    : path.resolve(projectRoot, folderPath);
+  // Resolve path - check imports first
+  let absolutePath: string;
+  if (path.isAbsolute(folderPath)) {
+    absolutePath = folderPath;
+  } else {
+    const importResolved = resolvePathWithImports(folderPath, packageRoot, [projectRoot]);
+    absolutePath = importResolved ?? path.resolve(projectRoot, folderPath);
+  }
 
   // Check if directory exists
   try {
@@ -174,14 +189,19 @@ async function loadPromptsFromFolder(
 
 /**
  * Load chained prompts from a path (file or folder)
+ * Checks imported packages first, then project root
  */
 async function loadPromptsFromPath(
   inputPath: string,
   projectRoot: string
 ): Promise<ChainedPrompt[]> {
-  const absolutePath = path.isAbsolute(inputPath)
-    ? inputPath
-    : path.resolve(projectRoot, inputPath);
+  let absolutePath: string;
+  if (path.isAbsolute(inputPath)) {
+    absolutePath = inputPath;
+  } else {
+    const importResolved = resolvePathWithImports(inputPath, packageRoot, [projectRoot]);
+    absolutePath = importResolved ?? path.resolve(projectRoot, inputPath);
+  }
 
   try {
     const stat = await fs.stat(absolutePath);

src/agents/runner/config.ts

@@ -3,6 +3,10 @@ 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 { resolvePackageRoot } from '../../shared/runtime/root.js';
+
+const packageRoot = resolvePackageRoot(import.meta.url, 'agent runner config');
 
 export type AgentConfig = AgentDefinition & {
   name: string;
@@ -65,10 +69,17 @@ export async function loadAgentTemplate(agentId: string, projectRoot?: string):
     throw new Error(`Agent ${agentId} has an invalid promptPath configuration`);
   }
 
-  // If path is absolute, use it directly; otherwise resolve relative to project root
-  const resolvedPromptPaths = promptSources.map(p =>
-    path.isAbsolute(p) ? p : path.resolve(resolvedRoot, p),
-  );
+  // If path is absolute, use it directly; otherwise check imports first, then project root
+  const resolvedPromptPaths = promptSources.map(p => {
+    if (path.isAbsolute(p)) return p;
+
+    // Try to resolve from imports first
+    const importResolved = resolvePromptPath(p, packageRoot);
+    if (importResolved) return importResolved;
+
+    // Fall back to project root
+    return path.resolve(resolvedRoot, p);
+  });
 
   const contentParts = await Promise.all(
     resolvedPromptPaths.map(promptPath => fs.readFile(promptPath, 'utf-8')),

src/shared/agents/config/paths.ts

@@ -1,24 +1,40 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { getAllInstalledImports } from '../../imports/index.js';
 
 const AGENT_MODULE_FILENAMES = ['sub.agents.js', 'main.agents.js', 'modules.js', 'agents.js'];
 const AGENT_JSON_RELATIVE_PATH = join('.codemachine', 'agents', 'agents-config.json');
 
 export type AgentsModuleLookupOptions = {
   projectRoot?: string;
+  /** Whether to also check imported packages */
+  checkImports?: boolean;
 };
 
 export function resolveAgentsModulePath(options: AgentsModuleLookupOptions = {}): string | undefined {
   const projectRoot = options.projectRoot ? resolve(options.projectRoot) : undefined;
-  if (!projectRoot) {
-    return undefined;
+  const checkImports = options.checkImports ?? true;
+
+  const candidates: string[] = [];
+
+  // Check imported packages first (they take precedence)
+  if (checkImports) {
+    const imports = getAllInstalledImports();
+    for (const imp of imports) {
+      for (const filename of AGENT_MODULE_FILENAMES) {
+        candidates.push(join(imp.resolvedPaths.config, filename));
+      }
+    }
   }
 
-  const candidates = [join(projectRoot, AGENT_JSON_RELATIVE_PATH)];
+  // Then check project root
+  if (projectRoot) {
+    candidates.push(join(projectRoot, AGENT_JSON_RELATIVE_PATH));
 
-  for (const filename of AGENT_MODULE_FILENAMES) {
-    candidates.push(join(projectRoot, 'config', filename));
-    candidates.push(join(projectRoot, 'dist', 'config', filename));
+    for (const filename of AGENT_MODULE_FILENAMES) {
+      candidates.push(join(projectRoot, 'config', filename));
+      candidates.push(join(projectRoot, 'dist', 'config', filename));
+    }
   }
 
   for (const candidate of candidates) {
@@ -29,3 +45,44 @@ export function resolveAgentsModulePath(options: AgentsModuleLookupOptions = {})
 
   return undefined;
 }
+
+/**
+ * Get all agent module paths including from imports
+ * Returns an array of all existing agent config paths
+ */
+export function getAllAgentsModulePaths(projectRoot?: string): string[] {
+  const paths: string[] = [];
+  const resolvedRoot = projectRoot ? resolve(projectRoot) : undefined;
+
+  // Check imported packages first
+  const imports = getAllInstalledImports();
+  for (const imp of imports) {
+    for (const filename of AGENT_MODULE_FILENAMES) {
+      const candidate = join(imp.resolvedPaths.config, filename);
+      if (existsSync(candidate)) {
+        paths.push(candidate);
+      }
+    }
+  }
+
+  // Then check project root
+  if (resolvedRoot) {
+    const jsonPath = join(resolvedRoot, AGENT_JSON_RELATIVE_PATH);
+    if (existsSync(jsonPath)) {
+      paths.push(jsonPath);
+    }
+
+    for (const filename of AGENT_MODULE_FILENAMES) {
+      const configPath = join(resolvedRoot, 'config', filename);
+      if (existsSync(configPath)) {
+        paths.push(configPath);
+      }
+      const distPath = join(resolvedRoot, 'dist', 'config', filename);
+      if (existsSync(distPath)) {
+        paths.push(distPath);
+      }
+    }
+  }
+
+  return paths;
+}

src/shared/agents/discovery/steps.ts

@@ -2,6 +2,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import * as path from 'node:path';
 
 import { loadWorkflowModule, isWorkflowTemplate } from '../../../workflows/index.js';
+import { getAllWorkflowDirectories } from '../../imports/index.js';
 
 export type WorkflowAgentDefinition = {
   id: string;
@@ -22,46 +23,85 @@ function discoverWorkflowFiles(root: string): string[] {
     .map((file) => path.resolve(baseDir, file));
 }
 
+/**
+ * Discover workflow files from all workflow directories including imports
+ */
+function discoverAllWorkflowFiles(localRoot: string): string[] {
+  const allFiles: string[] = [];
+  const seenDirs = new Set<string>();
+
+  // Get all workflow directories (imports + local)
+  const workflowDirs = getAllWorkflowDirectories(localRoot);
+
+  for (const dir of workflowDirs) {
+    if (seenDirs.has(dir) || !existsSync(dir)) continue;
+    seenDirs.add(dir);
+
+    const files = readdirSync(dir)
+      .filter((file) => file.endsWith('.workflow.js'))
+      .map((file) => path.resolve(dir, file));
+    allFiles.push(...files);
+  }
+
+  return allFiles;
+}
+
 export async function collectAgentsFromWorkflows(roots: string[]): Promise<WorkflowAgentDefinition[]> {
   const seenFiles = new Set<string>();
   const byId = new Map<string, WorkflowAgentDefinition>();
 
+  // Collect workflow files from all roots
+  const allWorkflowFiles: string[] = [];
+
   for (const root of roots) {
     if (!root) continue;
     const resolvedRoot = path.resolve(root);
+
+    // Use both traditional discovery and import-aware discovery
     for (const filePath of discoverWorkflowFiles(resolvedRoot)) {
-      if (seenFiles.has(filePath)) continue;
-      seenFiles.add(filePath);
+      allWorkflowFiles.push(filePath);
+    }
+  }
+
+  // Also discover from all import directories (handles case where imports aren't in roots)
+  if (roots.length > 0) {
+    const importFiles = discoverAllWorkflowFiles(roots[0]);
+    allWorkflowFiles.push(...importFiles);
+  }
+
+  // Process all discovered workflow files
+  for (const filePath of allWorkflowFiles) {
+    if (seenFiles.has(filePath)) continue;
+    seenFiles.add(filePath);
 
-      try {
-        const template = await loadWorkflowModule(filePath);
-        if (!isWorkflowTemplate(template)) {
+    try {
+      const template = await loadWorkflowModule(filePath);
+      if (!isWorkflowTemplate(template)) {
+        continue;
+      }
+
+      for (const step of template.steps ?? []) {
+        if (!step || step.type !== 'module') {
           continue;
         }
 
-        for (const step of template.steps ?? []) {
-          if (!step || step.type !== 'module') {
-            continue;
-          }
-
-          const id = typeof step.agentId === 'string' ? step.agentId.trim() : '';
-          if (!id) {
-            continue;
-          }
-
-          const existing = byId.get(id) ?? { id };
-          byId.set(id, {
-            ...existing,
-            id,
-            name: step.agentName ?? existing.name,
-            promptPath: step.promptPath ?? existing.promptPath,
-            model: step.model ?? existing.model,
-            modelReasoningEffort: step.modelReasoningEffort ?? existing.modelReasoningEffort,
-          });
+        const id = typeof step.agentId === 'string' ? step.agentId.trim() : '';
+        if (!id) {
+          continue;
         }
-      } catch {
-        // Ignore templates that fail to load; other files might still provide definitions.
+
+        const existing = byId.get(id) ?? { id };
+        byId.set(id, {
+          ...existing,
+          id,
+          name: step.agentName ?? existing.name,
+          promptPath: step.promptPath ?? existing.promptPath,
+          model: step.model ?? existing.model,
+          modelReasoningEffort: step.modelReasoningEffort ?? existing.modelReasoningEffort,
+        });
       }
+    } catch {
+      // Ignore templates that fail to load; other files might still provide definitions.
     }
   }
 

src/shared/imports/index.ts

@@ -51,3 +51,13 @@ export {
   resolveSource,
   extractRepoName,
 } from './resolver.js';
+
+// Import-aware path resolution
+export {
+  resolvePromptPath,
+  resolvePromptFolder,
+  resolveWorkflowTemplate,
+  resolvePathWithImports,
+  getAllWorkflowDirectories,
+  getAllPromptDirectories,
+} from './resolve.js';