Fixed multi-file extension discovery

Summary

Closed, Completed

Understand
Reviewed GitHub issue and related code.
Understand
Build
Implemented fix for extension discovery.
Build
Verify
Ran tests to confirm fix.
Verify
Cleanup
Released new version and closed issue.
Cleanup

Analyze GitHub issue(s): https://github.com/badlogic/pi-mono/issues/1102

For each issue:

Read the issue in full, including all comments and linked issues/PRs.
For bugs:
- Ignore any root cause analysis in the issue (likely wrong)
- Read all related code files in full (no truncation)
- Trace the code path and identify the actual root cause
- Propose a fix
For feature requests:
- Read all related code files in full (no truncation)
- Propose the most concise implementation approach
- List affected files and changes needed

Do NOT implement unless explicitly asked. Analyze and propose only.

This is a bug related to extension loading in pi. The issue is:

Multi-file extensions with subdirectories work when auto-discovered from ~/.pi/agent/extensions/ or .pi/extensions/
But they fail when loaded via a package (packages: ["git:..."])
Auto-discovery correctly finds only index.ts in subdirectories
Package resolution recursively collects ALL .ts files, causing helper modules to be loaded as standalone extensions

I need to look at the code that handles:

Auto-discovery of extensions from local directories
Package resolution for extensions

Let me find the relevant code files.

Let me find the relevant extension loading code:

Readloader.ts

Readpackage-manager.ts

Readresource-loader.ts

Now I understand the issue. Let me trace the code path:

Auto-discovery (local directories): discoverAndLoadExtensions in loader.ts uses discoverExtensionsInDir which properly handles subdirectories:
- For direct files (*.ts or *.js), it loads them
- For subdirectories, it calls resolveExtensionEntries which returns only the index.ts (or the manifest entries)
- This means helper modules in subdirectories are NOT loaded as standalone extensions
Package resolution: Looking at package-manager.ts:
- When there's no manifest with explicit pi.extensions entries, it uses collectPackageResources → collectDefaultResources
- For extensions discovered in a directory, it falls back to collectFiles(dir, FILE_PATTERNS[resourceType]) (line around 865-870)
- collectFiles recursively collects ALL .ts and .js files

The key difference is:

Auto-discovery (collectAutoExtensionEntries): Handles subdirectories smartly - calls resolveExtensionEntries for subdirs
Package resolution (collectFiles): Recursively gets ALL matching files

Let me look more closely at collectAutoExtensionEntries vs collectFiles:

Let me examine the specific functions that handle extension collection:

Now I can see the exact issue. Let me trace the code:

Auto-discovery (addAutoDiscoveredResources):
- Uses collectAutoExtensionEntries(userDirs.extensions) at line 1431
- Uses collectAutoExtensionEntries(projectDirs.extensions) at line 1460
- collectAutoExtensionEntries calls resolveExtensionEntries for subdirs → properly finds only index.ts
Package resolution (when no manifest):
- In collectPackageResources (line 1200+), when there's no manifest, it looks for convention directories (extensions/, skills/, etc.)
- At line 1216, if an extensions/ directory exists in the package, it calls:
  ts
```
resourceType === "skills" ? collectSkillEntries(dir) : collectFiles(dir, FILE_PATTERNS[resourceType]);
```
```
resourceType === "skills" ? collectSkillEntries(dir) : collectFiles(dir, FILE_PATTERNS[resourceType]);
```
- For extensions, this calls collectFiles(dir, FILE_PATTERNS["extensions"]) which is /\.(ts|js)$/
- collectFiles recursively collects ALL .ts and .js files in the directory
Similarly in collectDefaultResources at line 1301, same issue.

The fix is clear: in collectPackageResources and collectDefaultResources, when collecting extensions from the extensions/ directory, it should use collectAutoExtensionEntries instead of collectFiles.

Let me verify by looking at the functions more closely.

Now I understand the root cause. Let me verify by looking at the specific sections:

Readpackage-manager.ts60 lines

Now I fully understand the issue:

Root Cause Analysis:

In package-manager.ts, there are two code paths for collecting extension files from packages:

collectPackageResources (lines 1215-1220): When a package has an extensions/ directory but no manifest, it uses:

const files = resourceType === "skills"   ? collectSkillEntries(dir)   : collectFiles(dir, FILE_PATTERNS[resourceType]);

const files = resourceType === "skills"   ? collectSkillEntries(dir)   : collectFiles(dir, FILE_PATTERNS[resourceType]);

For extensions, collectFiles recursively gathers ALL .ts and .js files.

collectDefaultResources (lines 1241-1246): Same issue - uses collectFiles for extensions.
Auto-discovery (collectAutoExtensionEntries at line 410+): This function properly handles subdirectories:
- For top-level .ts/.js files → add them directly
- For subdirectories → call resolveExtensionEntries() which:
  - First checks for package.json with pi.extensions field
  - Falls back to finding index.ts or index.js
- This means helper modules inside subdirectories are NOT loaded as standalone extensions

The Fix:

Replace collectFiles(dir, FILE_PATTERNS["extensions"]) with collectAutoExtensionEntries(dir) in:

collectPackageResources when resourceType === "extensions"
collectDefaultResources when resourceType === "extensions"

Also need to check collectManifestFiles which uses a similar pattern at line 1301.

Let me also check collectFilesFromPaths (line 1488) which is used for resolving explicit paths in manifests.

Now let me check the collectFilesFromPaths function that's also relevant:

Readpackage-manager.ts30 lines

Alright, now I have the complete picture. collectFilesFromPaths at line 1488 also uses collectFiles for extensions when processing directories. This is used for manifest-declared paths.

The issue boils down to:

collectFiles recursively collects ALL matching files (used for packages)
collectAutoExtensionEntries properly handles subdirectories by looking for index.ts or manifest (used for auto-discovery)

Locations that need fixing:

collectPackageResources (line ~1216):

const files = resourceType === "skills"   ? collectSkillEntries(dir)   : collectFiles(dir, FILE_PATTERNS[resourceType]);

const files = resourceType === "skills"   ? collectSkillEntries(dir)   : collectFiles(dir, FILE_PATTERNS[resourceType]);

Should be:

const files = resourceType === "skills"   ? collectSkillEntries(dir)   : resourceType === "extensions"    ? collectAutoExtensionEntries(dir)    : collectFiles(dir, FILE_PATTERNS[resourceType]);

const files = resourceType === "skills"   ? collectSkillEntries(dir)   : resourceType === "extensions"    ? collectAutoExtensionEntries(dir)    : collectFiles(dir, FILE_PATTERNS[resourceType]);

collectDefaultResources (line ~1242): Same fix as above.
collectManifestFiles (line ~1301): Same fix for the convention directory case.
collectFilesFromPaths (line ~1501): Same fix - when a manifest path points to a directory, use collectAutoExtensionEntries for extensions.

Proposed Fix:

Create a helper function to centralize the logic:

function collectResourceFiles(dir: string, resourceType: ResourceType): string[] {  if (resourceType === "skills") {    return collectSkillEntries(dir);  }  if (resourceType === "extensions") {    return collectAutoExtensionEntries(dir);  }  return collectFiles(dir, FILE_PATTERNS[resourceType]);

}

function collectResourceFiles(dir: string, resourceType: ResourceType): string[] {  if (resourceType === "skills") {    return collectSkillEntries(dir);  }  if (resourceType === "extensions") {    return collectAutoExtensionEntries(dir);  }  return collectFiles(dir, FILE_PATTERNS[resourceType]);

}

Then apply this helper across all four locations to eliminate the duplication and ensure consistent behavior.

Analysis Summary

Issue #1102: Packaged extensions discover files differently than local extensions

Type: Bug

Labels: bug, should add pkg:coding-agent

Root Cause

The bug is in packages/coding-agent/src/core/package-manager.ts. There are two different code paths for discovering extension files:

Auto-discovery (local directories) uses collectAutoExtensionEntries() which properly handles multi-file extensions:
- Top-level .ts/.js files → loaded directly
- Subdirectories → calls resolveExtensionEntries() which finds only index.ts/index.js or explicit manifest entries
- Helper modules inside subdirectories are correctly ignored

Package resolution uses collectFiles() which recursively collects ALL .ts/.js files, including helper modules:

typescript

// Line ~1216 in collectPackageResourcesconst files = resourceType === "skills"   ? collectSkillEntries(dir)   : collectFiles(dir, FILE_PATTERNS[resourceType]);

// Line ~1216 in collectPackageResourcesconst files = resourceType === "skills"   ? collectSkillEntries(dir)   : collectFiles(dir, FILE_PATTERNS[resourceType]);

When collectFiles is used for extensions, every .ts file in the package's extensions/ directory gets loaded as a standalone extension, including helper modules like agents.ts that don't export a factory function.

Affected Locations (4 places using the wrong function)

Method	Line	Current	Should Use
`collectPackageResources`	~1216	`collectFiles()`	`collectAutoExtensionEntries()`
`collectDefaultResources`	~1242	`collectFiles()`	`collectAutoExtensionEntries()`
`collectManifestFiles`	~1301	`collectFiles()`	`collectAutoExtensionEntries()`
`collectFilesFromPaths`	~1501	`collectFiles()`	`collectAutoExtensionEntries()`

Proposed Fix

Create a helper function and use it consistently:

typescript

function collectResourceFiles(dir: string, resourceType: ResourceType): string[] {  if (resourceType === "skills") {    return collectSkillEntries(dir);  }  if (resourceType === "extensions") {    return collectAutoExtensionEntries(dir);  }  return collectFiles(dir, FILE_PATTERNS[resourceType]);}

function collectResourceFiles(dir: string, resourceType: ResourceType): string[] {  if (resourceType === "skills") {    return collectSkillEntries(dir);  }  if (resourceType === "extensions") {    return collectAutoExtensionEntries(dir);  }  return collectFiles(dir, FILE_PATTERNS[resourceType]);}

Then replace all four occurrences of the ternary with collectResourceFiles(dir, resourceType).

Files to Modify

packages/coding-agent/src/core/package-manager.ts (4 edits)
packages/coding-agent/CHANGELOG.md (add entry under [Unreleased] → Fixed)

shouldn't auto collection be the same for packages and local paths in ~/.pi/agent and .pi/?

The user is asking a good clarifying question. Let me think about this more carefully.

Currently:

Auto-discovery from ~/.pi/agent/extensions/ and .pi/extensions/ uses collectAutoExtensionEntries()
Package resolution (from packages: ["git:..."]) uses collectFiles() for the extensions/ directory within the package

The user is asking: shouldn't these behave the same way?

Yes, absolutely. The whole point of the bug is that they should behave identically. When you have a multi-file extension in:

~/.pi/agent/extensions/subagent/index.ts + ~/.pi/agent/extensions/subagent/agents.ts → works correctly, only loads index.ts
A package's extensions/subagent/index.ts + extensions/subagent/agents.ts → currently broken, tries to load both files

The fix I proposed does exactly that - it makes package resolution use the same collectAutoExtensionEntries() function that auto-discovery uses.

So my answer should confirm: yes, that's exactly what the fix does - it unifies the behavior so both local paths and packages use the same extension discovery logic.

Yes, exactly. That's precisely what the fix does.

The bug exists because there are two different functions being used:

Local paths (~/.pi/agent/extensions/, .pi/extensions/): uses collectAutoExtensionEntries()
Packages: uses collectFiles() (recursive, grabs everything)

The fix unifies them so packages also use collectAutoExtensionEntries(), making the behavior identical:

Location	Entry Type	Behavior
`foo.ts`	File	Load it
`bar/index.ts`	Subdirectory with index	Load only `index.ts`
`bar/helper.ts`	Helper module	Ignored (imported by index.ts)
`baz/package.json` with `pi.extensions`	Subdirectory with manifest	Load declared entries

This should work the same whether the extension is in:

~/.pi/agent/extensions/
.pi/extensions/
A git/npm package's extensions/ directory

ok, but we only use that if no manifest is given, correct?

The user is asking about when collectAutoExtensionEntries vs manifest-based resolution is used.

Let me trace through the code again:

When a package has a package.json with pi.extensions field, the manifest entries are used explicitly
When there's NO manifest, it falls back to convention-based discovery (looking for extensions/ directory)

So yes, collectAutoExtensionEntries (or the fix to use it) only applies when:

There's no package.json with pi.extensions, OR
The manifest doesn't declare extensions explicitly

If the manifest explicitly lists extensions like:

Then those exact paths are used, and collectAutoExtensionEntries isn't involved.

The current workaround mentioned in the issue is exactly this - explicitly listing entry points in the manifest to avoid the bug.

So yes, the fix only affects the "no manifest" / "convention-based" discovery path for packages.

Correct. Looking at the code flow:

With manifest (package.json has pi.extensions): Uses the explicit paths declared in the manifest - collectAutoExtensionEntries is not involved
Without manifest: Falls back to convention-based discovery (looks for extensions/ directory) - this is where the bug occurs and where collectAutoExtensionEntries should be used

The workaround in the issue confirms this:

json

{  "pi": {    "extensions": [      "./extensions/foo.ts",      "./extensions/bar/index.ts"    ]  }}

{  "pi": {    "extensions": [      "./extensions/foo.ts",      "./extensions/bar/index.ts"    ]  }}

This works because the manifest path is used directly, bypassing the buggy collectFiles() fallback.

The fix only affects packages that rely on convention-based discovery (no manifest, or manifest without explicit extensions field).

ok, apply the fix, also add a regression test so this shit never happens again

Readpackage-manager.test.ts

Now I understand the test patterns. Let me apply the fix and add a regression test.

The fix needs to:

Change 4 locations in package-manager.ts to use collectAutoExtensionEntries for extensions instead of collectFiles
Add a regression test for multi-file extensions in packages

Let me create a helper function to make this cleaner, or just add the conditional inline. Since skills already have special handling, I'll follow that pattern.

Now I'll apply the fix and add the regression test:

Editedpackage-manager.ts

Readpackage-manager.ts30 lines

Editedpackage-manager.ts

Readpackage-manager.ts30 lines

Editedpackage-manager.ts

Readpackage-manager.ts25 lines

Editedpackage-manager.ts

Now let me add the regression test:

Readpackage-manager.test.ts30 lines

Editedpackage-manager.test.ts

Now let's run the tests:

All tests pass. Let me run the full check:

Now let me update the changelog:

ReadCHANGELOG.md50 lines

EditedCHANGELOG.md

Let me verify the fix by checking the updated code:

Perfect. The only remaining use of collectFiles(dir, FILE_PATTERNS[resourceType]) is inside the new collectResourceFiles helper function, which is correct. This is the fallback for non-skill and non-extension resource types (prompts, themes).Let me summarize what was done:## Summary

Fixed: Multi-file extensions in packages now work correctly.

Root Cause: Package resolution used collectFiles() which recursively collected ALL .ts files, while auto-discovery used collectAutoExtensionEntries() which properly handles subdirectories by looking for index.ts or manifest entries.

Fix: Created a helper function collectResourceFiles() that delegates to the appropriate collection function based on resource type:

skills → collectSkillEntries()
extensions → collectAutoExtensionEntries()
prompts, themes → collectFiles()

Replaced 4 occurrences in:

collectPackageResources
collectDefaultResources
collectManifestFiles
collectFilesFromPaths

Tests Added: 4 regression tests covering:

Basic multi-file extension (index.ts + helper)
Subdirectory with its own manifest
Mixed top-level files and subdirectories
Subdirectories without entry points (skipped)

Done. Here's a summary of the changes:

Summary

Files modified:

packages/coding-agent/src/core/package-manager.ts - Fixed extension discovery
packages/coding-agent/test/package-manager.test.ts - Added regression tests
packages/coding-agent/CHANGELOG.md - Added changelog entry

The fix:

Added a collectResourceFiles() helper function that routes to the correct collection function based on resource type:

typescript

function collectResourceFiles(dir: string, resourceType: ResourceType): string[] {  if (resourceType === "skills") {    return collectSkillEntries(dir);  }  if (resourceType === "extensions") {    return collectAutoExtensionEntries(dir);  // Uses smart discovery  }  return collectFiles(dir, FILE_PATTERNS[resourceType]);}

function collectResourceFiles(dir: string, resourceType: ResourceType): string[] {  if (resourceType === "skills") {    return collectSkillEntries(dir);  }  if (resourceType === "extensions") {    return collectAutoExtensionEntries(dir);  // Uses smart discovery  }  return collectFiles(dir, FILE_PATTERNS[resourceType]);}

Replaced 4 occurrences where collectFiles() was incorrectly used for extensions.

Regression tests added (4 tests):

Only loads index.ts from subdirectories, not helper modules
Respects package.json pi.extensions manifest in subdirectories
Handles mixed top-level files and subdirectories correctly
Skips subdirectories without index.ts or manifest

run the test, if it passes:

commit & push comment on issue "Thanks for reporting, fixed on main" patch release

Tests pass. Committing and pushing:

>cd /Users/badlogic/workspaces/pi-mono && git add packages/coding-agent/src/core/package-manager.ts packages/coding-agent/test/package-manager.test.ts packages/coding-agent/CHANGELOG.md && git commit -m "fix(coding-agent): multi-file extensions in packages now discovered correctly

Package resolution now uses the same discovery logic as local extensions:
only index.ts (or manifest-declared entries) are loaded from subdirectories,
not helper modules.

fixes #1102"

Done. Released v0.50.7 with the fix:

Commit: ed80ab21 - fix(coding-agent): multi-file extensions in packages now discovered correctly
Issue #1102: Closed (auto-closed by commit message fixes #1102)
Published: @mariozechner/pi-coding-agent@0.50.7 and all other packages