salmon-loop 0.3.2 → 0.5.0

package/dist/core/context/gatherers/knowledge-gatherer.js

@@ -6,6 +6,7 @@ export class KnowledgeGatherer {
     static KNOWLEDGE_SUBDIR = 'knowledge';
     static SNAPSHOT_FILE = 'snapshot.json';
     static COMPACTION_THRESHOLD = 20; // Compact after 20 events
+    static MAX_DECISIONS = 50; // Keep only the most recent N decisions
     fileAdapter = new FileAdapter();
     async gather(req) {
         const { repoPath } = req;
@@ -15,6 +16,7 @@ export class KnowledgeGatherer {
             project_rules: undefined,
             architectural_decisions: [],
             user_preferences: undefined,
+            lessons_learned: [],
         };
         const allDeprecated = new Set();
         try {
@@ -50,28 +52,44 @@ export class KnowledgeGatherer {
                         data.deprecated_rules.forEach((r) => allDeprecated.add(r));
                     }
                     if (data.architectural_decisions) {
+                        if (!Array.isArray(aggregated.architectural_decisions)) {
+                            aggregated.architectural_decisions = [];
+                        }
                         aggregated.architectural_decisions.push(...data.architectural_decisions);
                     }
                     if (data.user_preferences) {
                         aggregated.user_preferences = data.user_preferences;
                     }
+                    if (data.lessons_learned && Array.isArray(data.lessons_learned)) {
+                        if (!Array.isArray(aggregated.lessons_learned)) {
+                            aggregated.lessons_learned = [];
+                        }
+                        aggregated.lessons_learned.push(...data.lessons_learned);
+                    }
                 }
-                catch {
+                catch (error) {
                     // Skip corrupted files
+                    getLogger().debug(`[KnowledgeGatherer] failed to load event file ${file}: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
             // Filter out deprecated rules from aggregated project_rules
             if (aggregated.project_rules) {
                 aggregated.project_rules = aggregated.project_rules.filter((r) => !allDeprecated.has(r));
             }
+            // Prune stale architectural decisions (keep only the most recent N)
+            if (aggregated.architectural_decisions &&
+                aggregated.architectural_decisions.length > KnowledgeGatherer.MAX_DECISIONS) {
+                aggregated.architectural_decisions = aggregated.architectural_decisions.slice(-KnowledgeGatherer.MAX_DECISIONS);
+            }
             // 3. Optional Compaction
             if (eventFiles.length >= KnowledgeGatherer.COMPACTION_THRESHOLD) {
                 // Run compaction in background (non-blocking)
                 this.compact(knowledgeDir, aggregated, eventFiles).catch((e) => getLogger().debug(`[KnowledgeGatherer] Compaction failed: ${e}`));
             }
         }
-        catch {
+        catch (error) {
             // Directory missing or other read errors, return empty aggregated state
+            getLogger().debug(`[KnowledgeGatherer] knowledge directory read failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         return {
             project_rules: aggregated.project_rules,
@@ -79,6 +97,7 @@ export class KnowledgeGatherer {
                 ? aggregated.architectural_decisions
                 : undefined,
             user_preferences: aggregated.user_preferences,
+            lessons_learned: aggregated.lessons_learned?.length ? aggregated.lessons_learned : undefined,
         };
     }
     async compact(knowledgeDir, aggregated, filesToMerge) {

package/dist/core/context/gatherers/metadata-gatherer.js

@@ -1,4 +1,5 @@
 import { FileAdapter } from '../../adapters/fs/file-adapter.js';
+import { getLogger } from '../../observability/logger.js';
 import { safeJoin } from '../../utils/path.js';
 export class MetadataGatherer {
     fileAdapter = new FileAdapter();
@@ -10,16 +11,18 @@ export class MetadataGatherer {
             const pkgRaw = await this.fileAdapter.readFile(safeJoin(repoPath, 'package.json'), 'utf-8');
             metadata.packageJson = JSON.parse(pkgRaw);
         }
-        catch {
-            // Ignored
+        catch (error) {
+            // Ignored - best-effort metadata
+            getLogger().debug(`[MetadataGatherer] package.json read failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         // 2. README.md (first 1000 chars)
         try {
             const readmeRaw = await this.fileAdapter.readFile(safeJoin(repoPath, 'README.md'), 'utf-8');
             metadata.readmeHeader = readmeRaw.slice(0, 1000);
         }
-        catch {
-            // Ignored
+        catch (error) {
+            // Ignored - best-effort metadata
+            getLogger().debug(`[MetadataGatherer] README.md read failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         // 3. AI Instructions (GEMINI.md, CLAUDE.md, ARCH.md)
         const aiFiles = ['GEMINI.md', 'CLAUDE.md', 'ARCH.md', '.gemini/ARCH.md'];
@@ -28,8 +31,9 @@ export class MetadataGatherer {
                 const content = await this.fileAdapter.readFile(safeJoin(repoPath, file), 'utf-8');
                 metadata.aiInstructions = (metadata.aiInstructions || '') + `\n--- ${file} ---\n${content}`;
             }
-            catch {
-                // Ignored
+            catch (error) {
+                // Ignored - best-effort metadata
+                getLogger().debug(`[MetadataGatherer] AI instruction file ${file} not found: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         // 4. List common config files
@@ -50,8 +54,9 @@ export class MetadataGatherer {
                 await this.fileAdapter.readFile(safeJoin(repoPath, config), 'utf-8');
                 metadata.configFiles.push(config);
             }
-            catch {
+            catch (error) {
                 // Ignored: config not found
+                getLogger().debug(`[MetadataGatherer] config file ${config} not found: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         return metadata;

package/dist/core/context/gatherers/ripgrep-gatherer.js

@@ -30,7 +30,8 @@ export class RipgrepGatherer {
             try {
                 entries = await fileAdapter.readdirWithTypes(absoluteCurrent);
             }
-            catch {
+            catch (error) {
+                getLogger().debug(`[RipgrepGatherer] readdir failed for ${absoluteCurrent}: ${error instanceof Error ? error.message : String(error)}`);
                 continue;
             }
             entries.sort((a, b) => a.name.localeCompare(b.name));
@@ -77,7 +78,8 @@ export class RipgrepGatherer {
                             return results;
                     }
                 }
-                catch {
+                catch (error) {
+                    getLogger().debug(`[RipgrepGatherer] file read failed for ${absoluteFile}: ${error instanceof Error ? error.message : String(error)}`);
                     continue;
                 }
             }
@@ -149,8 +151,9 @@ export class RipgrepGatherer {
                     });
                 }
             }
-            catch {
+            catch (error) {
                 // Ignore malformed JSON.
+                getLogger().debug(`[RipgrepGatherer] JSON parse failed for ripgrep output line: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         return results;

package/dist/core/context/service.js

@@ -119,6 +119,7 @@ export class ContextService {
             expectedTargetSetSignature;
         if (recordedTargetSetSignature !== expectedTargetSetSignature) {
             await this.cacheStore.delete(cacheKey);
+            this.deleteUpdater(cacheKey);
             this.cacheMetrics.misses += 1;
             return {
                 missReason: 'target_signature_mismatch',
@@ -128,6 +129,7 @@ export class ContextService {
         const nextSignature = await this.computeTrackedFilesSignature(repoPath, entry.trackedFiles);
         if (nextSignature !== entry.signature) {
             await this.cacheStore.delete(cacheKey);
+            this.deleteUpdater(cacheKey);
             this.cacheMetrics.misses += 1;
             return { missReason: 'signature_mismatch', targetSetSignature: expectedTargetSetSignature };
         }
@@ -165,7 +167,8 @@ export class ContextService {
                 const stat = await this.fileAdapter.stat(absoluteFile);
                 parts.push(this.formatStatSignature(relativeFile, stat));
             }
-            catch {
+            catch (error) {
+                getLogger().debug(`[ContextService] stat failed for ${relativeFile}: ${error instanceof Error ? error.message : String(error)}`);
                 parts.push(`${relativeFile}:missing`);
             }
         }
@@ -184,7 +187,8 @@ export class ContextService {
                 const stat = await this.fileAdapter.stat(gitPath);
                 parts.push(this.formatStatSignature(rel, stat));
             }
-            catch {
+            catch (error) {
+                getLogger().debug(`[ContextService] stat failed for ${rel}: ${error instanceof Error ? error.message : String(error)}`);
                 parts.push(`${rel}:missing`);
             }
         }
@@ -210,6 +214,7 @@ export class ContextService {
         if (!last || Date.now() - last <= this.cacheTtlMs)
             return false;
         await this.cacheStore.delete(cacheKey);
+        this.deleteUpdater(cacheKey);
         this.cacheMetrics.evictions += 1;
         return true;
     }
@@ -243,6 +248,7 @@ export class ContextService {
             }
             if (victimKey) {
                 await this.cacheStore.delete(victimKey);
+                this.deleteUpdater(victimKey);
                 this.cacheMetrics.evictions += 1;
             }
         }
@@ -253,6 +259,7 @@ export class ContextService {
                 const chunk = victims.slice(i, i + 10);
                 await Promise.all(chunk.map(async ([key]) => {
                     await this.cacheStore.delete(key);
+                    this.deleteUpdater(key);
                     this.cacheMetrics.evictions += 1;
                 }));
             }
@@ -285,6 +292,9 @@ export class ContextService {
         }
         return updater;
     }
+    deleteUpdater(key) {
+        this.updaters.delete(key);
+    }
     logDiff(key, diff) {
         if (!diff.addedFiles.length && !diff.modifiedFiles.length && !diff.removedFiles.length) {
             return;

package/dist/core/context/steps/context-gather.js

@@ -1,9 +1,12 @@
 import { FileAdapter } from '../../adapters/fs/file-adapter.js';
 import { LIMITS } from '../../config/limits.js';
+import { getLogger } from '../../observability/logger.js';
 import { ensureInSandbox, normalizePath, safeJoin } from '../../utils/path.js';
-import { outlineSource } from '../ast/source-outline.js';
+import { detectLang } from '../ast/skeleton-extractor.js';
+import { outlineSourceAsync } from '../ast/source-outline.js';
 import { CONTEXT_AUDIT_ACTION, CONTEXT_AUDIT_PHASE } from '../audit-constants.js';
 import { recordContextAuditEvent } from '../audit.js';
+import { getEffectivenessTracker } from '../effectiveness/tracker.js';
 import { extractKeywords } from '../keywords.js';
 import { assertNotAborted } from '../service-helpers.js';
 const fileAdapter = new FileAdapter();
@@ -18,7 +21,8 @@ async function readMatchedFileContent(req, file) {
             return null;
         return await fileAdapter.readFile(fullPath, 'utf-8');
     }
-    catch {
+    catch (error) {
+        getLogger().debug(`[ContextGather] readMatchedFileContent failed for ${file}: ${error instanceof Error ? error.message : String(error)}`);
         return null;
     }
 }
@@ -59,7 +63,7 @@ export function buildContextGatherStep(deps) {
                 kind: 'dependency',
                 mode: content ? 'full' : 'outline',
                 content: content ?? `ripgrep match at line ${snippet.line}: ${snippet.content}`,
-                outline: content ? outlineSource(content) : undefined,
+                outline: content ? await outlineSourceAsync(content, detectLang(file)) : undefined,
             });
         }
         recordContextAuditEvent(CONTEXT_AUDIT_ACTION.gatherCompleted, {
@@ -75,6 +79,13 @@ export function buildContextGatherStep(deps) {
             hasKnowledgeBase: Boolean(knowledgeBase),
             hasRuntimeArtifacts: Boolean(runtimeArtifacts),
         }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.gather });
+        // Record context usage for effectiveness tracking
+        const tracker = getEffectivenessTracker();
+        for (const file of astRes.relatedFiles) {
+            const tokens = file.content ? Math.ceil(file.content.length / 4) : 0;
+            const relevanceScore = file.mode === 'full' ? 80 : 40;
+            tracker.recordUsage(file.path, false, tokens, relevanceScore);
+        }
         return {
             req,
             diffScope,

package/dist/core/context/steps/context-targets.js

@@ -20,6 +20,7 @@ export function buildContextTargetsStep(deps) {
             definitionMap: ast.definitionMap,
             symbolMap: ast.symbolMap,
             churnByFile: gitHistory?.churnByFile,
+            contextFiles: req.contextFiles,
         });
         assertNotAborted(req.signal);
         recordContextAuditEvent(CONTEXT_AUDIT_ACTION.targetsResolved, {

package/dist/core/context/targeting/target-resolver.js

@@ -7,6 +7,8 @@ function reasonRank(reason) {
     switch (reason) {
         case 'explicit_path':
             return 100;
+        case 'context_file':
+            return 95;
         case 'symbol_definition':
             return 90;
         case 'diff_included':
@@ -140,6 +142,19 @@ function buildExplicitTargets(req) {
         evidence: 'instruction_path',
     })));
 }
+function buildContextFileTargets(contextFiles) {
+    if (!contextFiles || contextFiles.length === 0)
+        return [];
+    return dedupeTargets(contextFiles
+        .map((f) => normalizePath(f).replace(/^(\.\/|\/)+/, ''))
+        .filter(Boolean)
+        .map((path) => ({
+        path,
+        reason: 'context_file',
+        confidence: 'high',
+        evidence: 'context_files_option',
+    })));
+}
 function buildDiffTargets(includedFiles) {
     if (!includedFiles || includedFiles.length === 0)
         return [];
@@ -382,7 +397,7 @@ export class TargetResolver {
         };
     }
     async resolve(params) {
-        const { req, includedFiles, importRelatedFiles, rgHitFiles, definitionMap, symbolMap, diffusionDepth, maxDiffusionTargets, churnByFile, } = params;
+        const { req, includedFiles, importRelatedFiles, rgHitFiles, definitionMap, symbolMap, diffusionDepth, maxDiffusionTargets, churnByFile, contextFiles, } = params;
         const runner = new MicroTaskRunner({
             debugLabel: 'context-targeting',
             maxRounds: 5,
@@ -390,7 +405,8 @@ export class TargetResolver {
                 if (key === 'explicitTargets') {
                     const primary = buildPrimaryTarget(ctx.primaryFile);
                     const explicit = buildExplicitTargets(req);
-                    return dedupeTargets([...primary, ...explicit]);
+                    const contextFileTargets = buildContextFileTargets(contextFiles);
+                    return dedupeTargets([...primary, ...explicit, ...contextFileTargets]);
                 }
                 if (key === 'diffTargets') {
                     const primary = buildPrimaryTarget(ctx.primaryFile);
@@ -433,34 +449,36 @@ export class TargetResolver {
                 return [];
             },
             strategy: (engine) => {
+                const hasExplicitSignal = (data, key) => (data?.[key] || []).some((t) => t.reason === 'explicit_path' || t.reason === 'context_file');
+                const hasSymbolTargets = (data) => (data?.symbolTargets || []).some((t) => t.reason === 'symbol_definition');
+                const hasDiffTargets = (data) => (data?.diffTargets || []).some((t) => t.reason === 'diff_included');
                 return engine
                     .phase('Dependencies')
                     .requireData(['explicitTargets', 'symbolTargets', 'diffTargets', 'defaultTargets'])
                     .phase('Selection')
-                    .when((c) => (c.data?.explicitTargets || []).some((t) => t.reason === 'explicit_path'), (p) => {
+                    .when((c) => hasExplicitSignal(c.data, 'explicitTargets'), (p) => {
                     p.addAction('SET_TARGETS', {
                         strategy: 'explicit',
                         targets: engine.ctx.data.explicitTargets,
                     });
                 })
-                    .when((c) => !(c.data?.explicitTargets || []).some((t) => t.reason === 'explicit_path') &&
-                    (c.data?.symbolTargets || []).some((t) => t.reason === 'symbol_definition'), (p) => {
+                    .when((c) => !hasExplicitSignal(c.data, 'explicitTargets') && hasSymbolTargets(c.data), (p) => {
                     p.addAction('SET_TARGETS', {
                         strategy: 'symbol',
                         targets: engine.ctx.data.symbolTargets,
                     });
                 })
-                    .when((c) => !(c.data?.explicitTargets || []).some((t) => t.reason === 'explicit_path') &&
-                    !(c.data?.symbolTargets || []).some((t) => t.reason === 'symbol_definition') &&
-                    (c.data?.diffTargets || []).some((t) => t.reason === 'diff_included'), (p) => {
+                    .when((c) => !hasExplicitSignal(c.data, 'explicitTargets') &&
+                    !hasSymbolTargets(c.data) &&
+                    hasDiffTargets(c.data), (p) => {
                     p.addAction('SET_TARGETS', {
                         strategy: 'diff',
                         targets: engine.ctx.data.diffTargets,
                     });
                 })
-                    .unless((c) => (c.data?.explicitTargets || []).some((t) => t.reason === 'explicit_path') ||
-                    (c.data?.symbolTargets || []).some((t) => t.reason === 'symbol_definition') ||
-                    (c.data?.diffTargets || []).some((t) => t.reason === 'diff_included'), (p) => {
+                    .unless((c) => hasExplicitSignal(c.data, 'explicitTargets') ||
+                    hasSymbolTargets(c.data) ||
+                    hasDiffTargets(c.data), (p) => {
                     p.addAction('SET_TARGETS', {
                         strategy: 'default',
                         targets: engine.ctx.data.defaultTargets,

package/dist/core/context/token/cache.js

@@ -6,6 +6,7 @@
  */
 import { createHash } from 'crypto';
 import { FileAdapter } from '../../adapters/fs/file-adapter.js';
+import { getLogger } from '../../observability/logger.js';
 /**
  * Two-level token cache for performance optimization.
  *
@@ -82,8 +83,9 @@ export class TokenCache {
             this.fileCache.set(filePath, entry);
             return entry;
         }
-        catch {
+        catch (error) {
             // File doesn't exist or can't be accessed
+            getLogger().debug(`[TokenCache] file cache get failed for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
             this.fileCache.delete(filePath);
             this.misses++;
             return null;
@@ -108,8 +110,9 @@ export class TokenCache {
                 contentHash: this.hashContent(content),
             });
         }
-        catch {
+        catch (error) {
             // Ignore if file can't be accessed
+            getLogger().debug(`[TokenCache] file cache set failed for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     // ==================== Invalidation ====================

package/dist/core/context/token/encoding-registry.js

@@ -24,13 +24,13 @@ class TiktokenEncoding {
         this.initialized = true;
     }
     encode(text) {
-        this.ensureInitialized();
-        return Array.from(this.encoder.encode(text));
+        const encoder = this.getEncoder();
+        return Array.from(encoder.encode(text));
     }
     decode(tokens) {
-        this.ensureInitialized();
+        const encoder = this.getEncoder();
         const uint32Tokens = new Uint32Array(tokens);
-        const decoded = this.encoder.decode(uint32Tokens);
+        const decoded = encoder.decode(uint32Tokens);
         return new TextDecoder().decode(decoded);
     }
     count(text) {
@@ -43,10 +43,11 @@ class TiktokenEncoding {
         }
         this.initialized = false;
     }
-    ensureInitialized() {
-        if (!this.initialized || !this.encoder) {
+    getEncoder() {
+        if (!this.encoder) {
             throw new Error(`Encoding ${this.name} not initialized. Call initialize() first.`);
         }
+        return this.encoder;
     }
 }
 /**

package/dist/core/context/truncation/strategies/json.js

@@ -4,6 +4,7 @@
  * Preserves JSON structure while truncating large arrays/objects.
  * Keeps root structure and key names visible.
  */
+import { getLogger } from '../../../observability/logger.js';
 import { DEFAULT_TRUNCATION_CONFIG } from '../types.js';
 /**
  * JSON truncation strategy.
@@ -21,7 +22,8 @@ export class JsonStrategy {
             JSON.parse(output);
             return true;
         }
-        catch {
+        catch (error) {
+            getLogger().debug(`[JsonStrategy] canHandle parse check failed: ${error instanceof Error ? error.message : String(error)}`);
             return false;
         }
     }
@@ -40,8 +42,9 @@ export class JsonStrategy {
         try {
             parsed = JSON.parse(output);
         }
-        catch {
+        catch (error) {
             // Not valid JSON, fall back to simple truncation
+            getLogger().debug(`[JsonStrategy] JSON parse failed during truncation: ${error instanceof Error ? error.message : String(error)}`);
             return this.simpleTruncate(output, budget);
         }
         // Truncate while preserving structure

package/dist/core/context/truncation/type-detector.js

@@ -4,6 +4,7 @@
  * Analyzes output content to determine the most appropriate
  * truncation strategy.
  */
+import { getLogger } from '../../observability/logger.js';
 /**
  * Detection patterns for each output type.
  */
@@ -84,8 +85,9 @@ export function detectOutputType(output) {
         try {
             JSON.parse(output);
         }
-        catch {
+        catch (error) {
             // Not valid JSON, downgrade to generic
+            getLogger().debug(`[TypeDetector] JSON validation failed: ${error instanceof Error ? error.message : String(error)}`);
             bestType = 'generic';
             bestScore = 0;
         }

package/dist/core/extensions/index.js

@@ -3,9 +3,9 @@ import { buildResolvedMcpServersV2 } from '../mcp/config/index.js';
 import { getLogger } from '../observability/logger.js';
 import { loadConfig } from './load.js';
 import { mergeScopedEntries } from './merge.js';
-import { expandHome, getRepoMcpConfigPath, getRepoSkillConfigPath, getRepoToolConfigPath, getUserMcpConfigPath, getUserSkillConfigPath, getUserToolConfigPath, isWithinRoot, resolveRepoRelative, resolveUserRelative, } from './paths.js';
+import { expandHome, getRepoAgentsConfigPath, getRepoMcpConfigPath, getRepoSkillConfigPath, getRepoToolConfigPath, getUserAgentsConfigPath, getUserMcpConfigPath, getUserSkillConfigPath, getUserToolConfigPath, isWithinRoot, resolveRepoRelative, resolveUserRelative, } from './paths.js';
 import { redactExtensions } from './redact.js';
-import { McpConfigSchema, SkillsConfigSchema, ToolsConfigSchema } from './schemas.js';
+import { AgentsConfigSchema, McpConfigSchema, SkillsConfigSchema, ToolsConfigSchema, } from './schemas.js';
 function defaultEnabled(scope) {
     return scope === 'repo';
 }
@@ -29,6 +29,47 @@ function buildResolvedPlugins(entries, repoRoot) {
         };
     });
 }
+function buildResolvedAgentProfiles(user, repo) {
+    const seen = new Map();
+    // User profiles first (lower priority)
+    if (user) {
+        for (const agent of user.agents) {
+            if (agent.enabled === false)
+                continue;
+            seen.set(agent.id, toResolvedProfile(agent, 'user'));
+        }
+    }
+    // Repo profiles override user profiles (higher priority)
+    if (repo) {
+        for (const agent of repo.agents) {
+            if (agent.enabled === false) {
+                seen.delete(agent.id);
+                continue;
+            }
+            seen.set(agent.id, toResolvedProfile(agent, 'repo'));
+        }
+    }
+    return Array.from(seen.values());
+}
+function toResolvedProfile(raw, scope) {
+    return {
+        id: raw.id,
+        name: raw.name,
+        role: raw.role,
+        description: raw.description,
+        allowedTools: raw.allowedTools ?? ['code.search', 'fs.read'],
+        readOnly: raw.readOnly ?? false,
+        stratagem: raw.stratagem ?? 'investigator',
+        toolInheritance: raw.toolInheritance,
+        permissionMode: raw.permissionMode,
+        systemPrompt: raw.systemPrompt,
+        maxTokens: raw.maxTokens,
+        maxAttempts: raw.maxAttempts,
+        timeoutMs: raw.timeoutMs,
+        model: raw.model,
+        scope,
+    };
+}
 function buildResolvedSkills(user, repo, repoRoot) {
     const repoDiscovery = repo?.discovery;
     const userDiscovery = user?.discovery;
@@ -73,13 +114,15 @@ function buildResolvedSkills(user, repo, repoRoot) {
 }
 export async function resolveExtensions(options) {
     const { repoRoot } = options;
-    const [userMcp, repoMcp, userTools, repoTools, userSkills, repoSkills] = await Promise.all([
+    const [userMcp, repoMcp, userTools, repoTools, userSkills, repoSkills, userAgents, repoAgents] = await Promise.all([
         loadConfig(getUserMcpConfigPath(), McpConfigSchema),
         loadConfig(getRepoMcpConfigPath(repoRoot), McpConfigSchema),
         loadConfig(getUserToolConfigPath(), ToolsConfigSchema),
         loadConfig(getRepoToolConfigPath(repoRoot), ToolsConfigSchema),
         loadConfig(getUserSkillConfigPath(), SkillsConfigSchema),
         loadConfig(getRepoSkillConfigPath(repoRoot), SkillsConfigSchema),
+        loadConfig(getUserAgentsConfigPath(), AgentsConfigSchema),
+        loadConfig(getRepoAgentsConfigPath(repoRoot), AgentsConfigSchema),
     ]);
     const mergedServers = mergeScopedEntries(userMcp?.config.servers, repoMcp?.config.servers);
     const mergedPlugins = mergeScopedEntries(userTools?.config.plugins, repoTools?.config.plugins);
@@ -87,11 +130,13 @@ export async function resolveExtensions(options) {
         mcpServers: buildResolvedMcpServersV2(mergedServers, repoRoot),
         toolPlugins: buildResolvedPlugins(mergedPlugins, repoRoot),
         skillDiscovery: buildResolvedSkills(userSkills?.config, repoSkills?.config, repoRoot),
+        agentProfiles: buildResolvedAgentProfiles(userAgents?.config, repoAgents?.config),
     };
     const rawEffective = {
         mcp: repoMcp?.config ?? userMcp?.config ?? null,
         tools: repoTools?.config ?? userTools?.config ?? null,
         skills: repoSkills?.config ?? userSkills?.config ?? null,
+        agents: repoAgents?.config ?? userAgents?.config ?? null,
     };
     return {
         resolved,

package/dist/core/extensions/load.js

@@ -1,4 +1,5 @@
 import { syncFs as fs } from '../adapters/fs/node-fs.js';
+import { errorMessage } from '../utils/error.js';
 export class ExtensionConfigError extends Error {
     path;
     constructor(path, message) {
@@ -18,7 +19,7 @@ export async function tryLoadJsonFile(path) {
             : undefined) === 'ENOENT') {
             return { exists: false };
         }
-        throw new ExtensionConfigError(path, (error instanceof Error ? error.message : String(error)) || 'Unable to read file');
+        throw new ExtensionConfigError(path, errorMessage(error) || 'Unable to read file');
     }
 }
 export async function loadConfig(path, schema) {
@@ -30,7 +31,7 @@ export async function loadConfig(path, schema) {
         return { path, config };
     }
     catch (error) {
-        throw new ExtensionConfigError(path, (error instanceof Error ? error.message : String(error)) || 'Schema validation failed');
+        throw new ExtensionConfigError(path, errorMessage(error) || 'Schema validation failed');
     }
 }
 //# sourceMappingURL=load.js.map

package/dist/core/extensions/merge.js

@@ -11,7 +11,10 @@ export function mergeScopedEntries(user, repo) {
             if (previous) {
                 merged.set(key, {
                     key,
-                    entry: { ...previous.entry, ...entry },
+                    entry: {
+                        ...previous.entry,
+                        ...entry,
+                    },
                     scope: 'repo',
                 });
             }
@@ -38,6 +41,7 @@ export function mergeResolvedExtensions(base, overlay) {
                 : base.skillDiscovery.scope,
             paths: [...base.skillDiscovery.paths, ...overlay.skillDiscovery.paths],
         },
+        agentProfiles: [...base.agentProfiles, ...overlay.agentProfiles],
     };
 }
 //# sourceMappingURL=merge.js.map

package/dist/core/extensions/paths.js

@@ -39,6 +39,12 @@ export function getUserToolConfigPath() {
 export function getUserSkillConfigPath() {
     return path.join(USER_CONFIG_DIR, 'skills-user.json');
 }
+export function getRepoAgentsConfigPath(repoRoot) {
+    return path.join(repoRoot, REPO_CONFIG_DIR, 'agents.json');
+}
+export function getUserAgentsConfigPath() {
+    return path.join(USER_CONFIG_DIR, 'agents-user.json');
+}
 /**
  * Check whether a candidate path resides within (or equals) a given root directory.
  *
@@ -60,11 +66,11 @@ export function isWithinRoot(candidate, root) {
         const realRoot = realpathSync(resolvedRoot);
         return realCandidate === realRoot || realCandidate.startsWith(realRoot + path.sep);
     }
-    catch {
+    catch (error) {
         // Candidate or root does not exist yet — fall back to lexical check.
         // This allows pre-declaring paths that will be created later, while
         // still catching obvious traversal sequences like `../../etc`.
-        tryGetLogger()?.debug(`isWithinRoot: path not on disk, using lexical check for "${candidate}" against root "${root}"`);
+        tryGetLogger()?.debug(`[Paths] isWithinRoot: path not on disk, using lexical check for "${candidate}" against root "${root}": ${error instanceof Error ? error.message : String(error)}`);
         return (resolvedCandidate === resolvedRoot || resolvedCandidate.startsWith(resolvedRoot + path.sep));
     }
 }