@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/search/query.js

@@ -0,0 +1,15 @@
+export function normalizeSearchQuery(queryText) {
+    const terms = queryText
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/u)
+        .map((term) => term.trim())
+        .filter(Boolean);
+    return {
+        raw: queryText,
+        normalized: terms.join(' '),
+        terms,
+    };
+}
+export function defaultLaneCandidatePoolLimit(finalLimit) {
+    return Math.max(25, Math.max(1, finalLimit) * 3);
+}

package/node_modules/@ktx/context/dist/search/query.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/search/query.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { defaultLaneCandidatePoolLimit, normalizeSearchQuery } from './query.js';
+describe('search query helpers', () => {
+    it('normalizes punctuation and duplicate terms into stable lowercase tokens', () => {
+        expect(normalizeSearchQuery('  Gross-Revenue, gross_revenue! Paid orders  ')).toEqual({
+            raw: '  Gross-Revenue, gross_revenue! Paid orders  ',
+            normalized: 'gross revenue gross_revenue paid orders',
+            terms: ['gross', 'revenue', 'gross_revenue', 'paid', 'orders'],
+        });
+    });
+    it('returns an empty normalized query for punctuation-only input', () => {
+        expect(normalizeSearchQuery('--- ///')).toEqual({
+            raw: '--- ///',
+            normalized: '',
+            terms: [],
+        });
+    });
+    it('sizes per-lane candidate pools before final limiting', () => {
+        expect(defaultLaneCandidatePoolLimit(1)).toBe(25);
+        expect(defaultLaneCandidatePoolLimit(8)).toBe(25);
+        expect(defaultLaneCandidatePoolLimit(10)).toBe(30);
+    });
+});

package/node_modules/@ktx/context/dist/search/rrf.d.ts

@@ -0,0 +1,5 @@
+import type { FusedSearchCandidate, SearchLaneName } from './types.js';
+export declare const DEFAULT_RRF_K = 60;
+export declare const DEFAULT_SEARCH_LANE_WEIGHTS: Record<SearchLaneName, number>;
+export declare function rrfContribution(weight: number, rank: number, rrfK?: number): number;
+export declare function compareFusedSearchCandidates(left: FusedSearchCandidate, right: FusedSearchCandidate): number;

package/node_modules/@ktx/context/dist/search/rrf.js

@@ -0,0 +1,13 @@
+export const DEFAULT_RRF_K = 60;
+export const DEFAULT_SEARCH_LANE_WEIGHTS = {
+    semantic: 2,
+    dictionary: 2,
+    lexical: 1.5,
+    token: 0.75,
+};
+export function rrfContribution(weight, rank, rrfK = DEFAULT_RRF_K) {
+    return weight / (rrfK + rank);
+}
+export function compareFusedSearchCandidates(left, right) {
+    return right.score - left.score || right.matchReasons.length - left.matchReasons.length || left.id.localeCompare(right.id);
+}

package/node_modules/@ktx/context/dist/search/rrf.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/search/rrf.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { compareFusedSearchCandidates, DEFAULT_SEARCH_LANE_WEIGHTS, rrfContribution } from './rrf.js';
+describe('RRF scoring', () => {
+    it('uses the shared lane weights from the hybrid search spec', () => {
+        expect(DEFAULT_SEARCH_LANE_WEIGHTS).toEqual({
+            semantic: 2,
+            dictionary: 2,
+            lexical: 1.5,
+            token: 0.75,
+        });
+    });
+    it('calculates a weighted RRF contribution with k=60 by default', () => {
+        expect(rrfContribution(2, 1)).toBeCloseTo(2 / 61, 12);
+        expect(rrfContribution(1.5, 2)).toBeCloseTo(1.5 / 62, 12);
+    });
+    it('sorts fused candidates by score, lane count, and stable id', () => {
+        const first = {
+            id: 'orders',
+            score: 0.05,
+            matchReasons: ['lexical'],
+            ranksByLane: { lexical: 1 },
+            rawScoresByLane: {},
+            evidenceByLane: {},
+        };
+        const second = {
+            id: 'customers',
+            score: 0.05,
+            matchReasons: ['lexical', 'semantic'],
+            ranksByLane: { lexical: 2, semantic: 1 },
+            rawScoresByLane: {},
+            evidenceByLane: {},
+        };
+        const third = {
+            id: 'accounts',
+            score: 0.04,
+            matchReasons: ['semantic'],
+            ranksByLane: { semantic: 1 },
+            rawScoresByLane: {},
+            evidenceByLane: {},
+        };
+        expect([first, second, third].sort(compareFusedSearchCandidates).map((candidate) => candidate.id)).toEqual([
+            'customers',
+            'orders',
+            'accounts',
+        ]);
+    });
+});

package/node_modules/@ktx/context/dist/search/types.d.ts

@@ -0,0 +1,73 @@
+export type SearchLaneName = 'lexical' | 'semantic' | 'dictionary' | 'token' | string;
+export type SearchLaneStatus = 'available' | 'skipped' | 'failed';
+export interface NormalizedSearchQuery {
+    raw: string;
+    normalized: string;
+    terms: string[];
+}
+export interface SearchCandidate {
+    id: string;
+    rank: number;
+    rawScore?: number;
+    matchReason?: string;
+    evidence?: unknown;
+}
+export interface SearchCandidateGeneratorArgs {
+    queryText: string;
+    normalizedQuery: NormalizedSearchQuery;
+    finalLimit: number;
+    laneCandidatePoolLimit: number;
+}
+export interface SearchLaneResult {
+    status?: SearchLaneStatus;
+    candidates: SearchCandidate[];
+    effectiveCandidatePoolLimit?: number;
+    reason?: string;
+}
+export interface SearchCandidateGenerator {
+    lane: SearchLaneName;
+    weight?: number;
+    generate(args: SearchCandidateGeneratorArgs): Promise<SearchLaneResult>;
+}
+export interface HybridSearchOptions {
+    queryText: string;
+    limit: number;
+    candidatePoolLimit?: number;
+    rrfK?: number;
+    laneWeights?: Partial<Record<SearchLaneName, number>>;
+    generators: SearchCandidateGenerator[];
+}
+export interface SearchLaneBreakdown {
+    lane: SearchLaneName;
+    status: SearchLaneStatus;
+    requestedCandidatePoolLimit: number;
+    effectiveCandidatePoolLimit: number;
+    returnedCandidateCount: number;
+    weight: number;
+    reason?: string;
+}
+export interface FusedSearchCandidate {
+    id: string;
+    score: number;
+    matchReasons: SearchLaneName[];
+    ranksByLane: Record<SearchLaneName, number>;
+    rawScoresByLane: Record<SearchLaneName, number>;
+    evidenceByLane: Record<SearchLaneName, unknown[]>;
+}
+export interface SearchResultHydrator<TResult> {
+    hydrate(candidates: FusedSearchCandidate[]): Promise<TResult[]>;
+}
+export interface HybridSearchResult {
+    query: NormalizedSearchQuery;
+    requestedLimit: number;
+    requestedCandidatePoolLimit: number;
+    results: FusedSearchCandidate[];
+    lanes: SearchLaneBreakdown[];
+}
+export interface SearchBackendCapabilities {
+    fts: boolean;
+    vector: boolean;
+    fuzzy: boolean;
+    jsonSearch: boolean;
+    arraySearch: boolean;
+}

package/node_modules/@ktx/context/dist/search/types.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/skills/index.d.ts

@@ -0,0 +1,2 @@
+export type { FrontmatterFields, SkillCaller, SkillMetadata, SkillsRegistryServiceOptions } from './skills-registry.service.js';
+export { SkillsRegistryService } from './skills-registry.service.js';

package/node_modules/@ktx/context/dist/skills/index.js

@@ -0,0 +1 @@
+export { SkillsRegistryService } from './skills-registry.service.js';

package/node_modules/@ktx/context/dist/skills/skills-registry.service.d.ts

@@ -0,0 +1,35 @@
+import { type KtxLogger } from '../core/index.js';
+export type SkillCaller = 'research' | 'memory_agent';
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    path: string;
+    callers?: SkillCaller[];
+}
+export interface FrontmatterFields {
+    name?: string;
+    description?: string;
+    callers?: SkillCaller[];
+}
+export interface SkillsRegistryServiceOptions {
+    skillsDir: string;
+    additionalSkillDirs?: string[];
+    logger?: KtxLogger;
+}
+export declare class SkillsRegistryService {
+    private readonly logger;
+    private readonly skillsDir;
+    private readonly additionalSkillDirs;
+    private catalogPromise;
+    constructor(options: SkillsRegistryServiceOptions);
+    private loadCatalog;
+    discoverSkills(rootDir: string): Promise<Map<string, SkillMetadata>>;
+    private discoverAllSkills;
+    parseFrontmatter(content: string): FrontmatterFields;
+    stripFrontmatter(content: string): string;
+    listSkills(namesOrCaller?: string[] | SkillCaller, caller?: SkillCaller): Promise<SkillMetadata[]>;
+    getSkill(name: string, caller?: SkillCaller): Promise<SkillMetadata | null>;
+    isAllowedFor(skill: SkillMetadata, caller: SkillCaller): boolean;
+    buildSkillsPrompt(skills: SkillMetadata[], caller?: SkillCaller): string;
+    private parseCallersValue;
+}

package/node_modules/@ktx/context/dist/skills/skills-registry.service.js

@@ -0,0 +1,215 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { noopLogger } from '../core/index.js';
+const SKILL_FILENAME = 'SKILL.md';
+const VALID_CALLERS = new Set(['research', 'memory_agent']);
+export class SkillsRegistryService {
+    logger;
+    skillsDir;
+    additionalSkillDirs;
+    catalogPromise = null;
+    constructor(options) {
+        this.logger = options.logger ?? noopLogger;
+        this.skillsDir = options.skillsDir;
+        this.additionalSkillDirs = options.additionalSkillDirs ?? [];
+    }
+    async loadCatalog() {
+        if (!this.catalogPromise) {
+            this.catalogPromise = this.discoverAllSkills();
+        }
+        return this.catalogPromise;
+    }
+    async discoverSkills(rootDir) {
+        const catalog = new Map();
+        let entries;
+        try {
+            entries = await readdir(rootDir);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Skills directory not found or unreadable at ${rootDir}: ${message}`);
+            return catalog;
+        }
+        for (const entry of entries.sort()) {
+            const dir = join(rootDir, entry);
+            const skillFile = join(dir, SKILL_FILENAME);
+            let isDir = false;
+            try {
+                isDir = (await stat(dir)).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (!isDir) {
+                continue;
+            }
+            let content;
+            try {
+                content = await readFile(skillFile, 'utf-8');
+            }
+            catch {
+                this.logger.warn(`Skipping skill directory '${entry}': missing ${SKILL_FILENAME}`);
+                continue;
+            }
+            const frontmatter = this.parseFrontmatter(content);
+            if (!frontmatter.name || !frontmatter.description) {
+                this.logger.warn(`Skipping skill '${entry}': frontmatter missing name or description`);
+                continue;
+            }
+            const key = frontmatter.name.toLowerCase();
+            if (catalog.has(key)) {
+                this.logger.warn(`Duplicate skill name '${frontmatter.name}' in '${entry}'; first found wins`);
+                continue;
+            }
+            catalog.set(key, {
+                name: frontmatter.name,
+                description: frontmatter.description,
+                path: dir,
+                callers: frontmatter.callers,
+            });
+        }
+        this.logger.log(`Discovered ${catalog.size} skill(s): ${[...catalog.values()].map((skill) => skill.name).join(', ')}`);
+        return catalog;
+    }
+    async discoverAllSkills() {
+        const catalog = new Map();
+        for (const rootDir of [this.skillsDir, ...this.additionalSkillDirs]) {
+            const discovered = await this.discoverSkills(rootDir);
+            for (const [key, skill] of discovered) {
+                if (!catalog.has(key)) {
+                    catalog.set(key, skill);
+                }
+            }
+        }
+        return catalog;
+    }
+    parseFrontmatter(content) {
+        if (!content.startsWith('---')) {
+            return {};
+        }
+        const end = content.indexOf('\n---', 3);
+        if (end === -1) {
+            return {};
+        }
+        const block = content.slice(3, end).trim();
+        const fields = {};
+        let index = 0;
+        const lines = block.split(/\r?\n/);
+        while (index < lines.length) {
+            const line = lines[index];
+            const match = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+            if (!match) {
+                index += 1;
+                continue;
+            }
+            const [, key, rest] = match;
+            let value = rest.trim();
+            const continuation = [];
+            let nextIndex = index + 1;
+            while (nextIndex < lines.length) {
+                const next = lines[nextIndex];
+                if (!next.trim() || /^[A-Za-z_][\w-]*:/.test(next) || !/^\s/.test(next)) {
+                    break;
+                }
+                continuation.push(next.trim());
+                nextIndex += 1;
+            }
+            if (continuation.length > 0) {
+                value = [value, ...continuation].filter(Boolean).join(' ');
+            }
+            if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            if (key === 'name' || key === 'description') {
+                fields[key] = value;
+            }
+            else if (key === 'callers') {
+                fields.callers = this.parseCallersValue(value);
+            }
+            index = nextIndex;
+        }
+        return fields;
+    }
+    stripFrontmatter(content) {
+        if (!content.startsWith('---')) {
+            return content;
+        }
+        const end = content.indexOf('\n---', 3);
+        if (end === -1) {
+            return content;
+        }
+        return content.slice(end + 4).replace(/^(?:\r?\n)+/, '');
+    }
+    async listSkills(namesOrCaller, caller) {
+        let names;
+        let resolvedCaller;
+        if (Array.isArray(namesOrCaller)) {
+            names = namesOrCaller;
+            resolvedCaller = caller;
+        }
+        else if (typeof namesOrCaller === 'string') {
+            resolvedCaller = namesOrCaller;
+        }
+        const catalog = await this.loadCatalog();
+        let skills = [...catalog.values()].sort((left, right) => left.name.localeCompare(right.name));
+        if (resolvedCaller) {
+            skills = skills.filter((skill) => this.isAllowedFor(skill, resolvedCaller));
+        }
+        if (!names || names.length === 0) {
+            return skills;
+        }
+        const requested = new Set(names.map((name) => name.toLowerCase()));
+        return skills.filter((skill) => requested.has(skill.name.toLowerCase()));
+    }
+    async getSkill(name, caller) {
+        const catalog = await this.loadCatalog();
+        const skill = catalog.get(name.toLowerCase()) ?? null;
+        if (!skill) {
+            return null;
+        }
+        if (caller && !this.isAllowedFor(skill, caller)) {
+            return null;
+        }
+        return skill;
+    }
+    isAllowedFor(skill, caller) {
+        if (!skill.callers || skill.callers.length === 0) {
+            return true;
+        }
+        return skill.callers.includes(caller);
+    }
+    buildSkillsPrompt(skills, caller) {
+        if (skills.length === 0) {
+            return '';
+        }
+        const list = skills.map((skill) => `- ${skill.name}: ${skill.description}`).join('\n');
+        const captureNote = caller === 'research'
+            ? '\n\nKnowledge pages and semantic-layer sources are captured automatically by a post-turn memory agent. Focus on answering, not on saving. Use `knowledge_read`/`knowledge_search` and `sl_read_source` to consult what already exists; the memory agent will write any new conventions or measures the turn surfaces.'
+            : '';
+        return `\n## Skills\n\nUse the \`load_skill\` tool to load a skill when the task benefits from specialized instructions.${captureNote}\n\nAvailable skills:\n${list}\n`;
+    }
+    parseCallersValue(raw) {
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            return undefined;
+        }
+        const inner = trimmed.startsWith('[') && trimmed.endsWith(']') ? trimmed.slice(1, -1) : trimmed;
+        const parts = inner
+            .split(',')
+            .map((part) => part.trim().replace(/^['"]|['"]$/g, ''))
+            .filter(Boolean);
+        if (parts.length === 0) {
+            return undefined;
+        }
+        const valid = [];
+        for (const part of parts) {
+            if (VALID_CALLERS.has(part)) {
+                valid.push(part);
+            }
+            else {
+                this.logger.warn(`Unknown caller '${part}' in skill frontmatter; ignoring`);
+            }
+        }
+        return valid.length > 0 ? valid : undefined;
+    }
+}

package/node_modules/@ktx/context/dist/skills/skills-registry.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/skills/skills-registry.service.test.js

@@ -0,0 +1,161 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { SkillsRegistryService } from './skills-registry.service.js';
+describe('SkillsRegistryService', () => {
+    let service;
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'skills-registry-'));
+        service = new SkillsRegistryService({ skillsDir: tempDir });
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    const writeSkill = async (dirName, body) => {
+        const dir = join(tempDir, dirName);
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, 'SKILL.md'), body, 'utf-8');
+    };
+    describe('parseFrontmatter', () => {
+        it('parses name and description', () => {
+            const frontmatter = service.parseFrontmatter('---\nname: foo\ndescription: Bar baz\n---\n\n# body');
+            expect(frontmatter).toEqual({ name: 'foo', description: 'Bar baz' });
+        });
+        it('supports wrapped description continuation lines', () => {
+            const frontmatter = service.parseFrontmatter(['---', 'name: sl', 'description: Line one', '  continuation of the description.', '---', '', '# body'].join('\n'));
+            expect(frontmatter.name).toBe('sl');
+            expect(frontmatter.description).toContain('Line one');
+            expect(frontmatter.description).toContain('continuation');
+        });
+        it('returns empty fields when no frontmatter block', () => {
+            expect(service.parseFrontmatter('# just a heading')).toEqual({});
+        });
+    });
+    describe('stripFrontmatter', () => {
+        it('removes the frontmatter block and leading blank line', () => {
+            const body = '---\nname: x\ndescription: y\n---\n\n# Hello\n\nparagraph';
+            expect(service.stripFrontmatter(body)).toBe('# Hello\n\nparagraph');
+        });
+        it('is a no-op when no frontmatter exists', () => {
+            expect(service.stripFrontmatter('# hello')).toBe('# hello');
+        });
+    });
+    describe('discoverSkills', () => {
+        it('returns an empty map when the directory does not exist', async () => {
+            const catalog = await service.discoverSkills(join(tempDir, 'missing'));
+            expect(catalog.size).toBe(0);
+        });
+        it('discovers valid skills and skips invalid ones', async () => {
+            await writeSkill('sl', '---\nname: sl\ndescription: Semantic layer.\n---\n\n# SL');
+            await writeSkill('knowledge_capture', '---\nname: knowledge_capture\ndescription: Wiki capture.\n---\n\n# KC');
+            await writeSkill('broken', '# no frontmatter at all');
+            await mkdir(join(tempDir, 'not_a_skill'), { recursive: true });
+            const catalog = await service.discoverSkills(tempDir);
+            expect(catalog.size).toBe(2);
+            expect(catalog.get('sl')?.name).toBe('sl');
+            expect(catalog.get('knowledge_capture')?.description).toContain('Wiki capture');
+            expect(catalog.has('broken')).toBe(false);
+        });
+    });
+    describe('buildSkillsPrompt', () => {
+        it('formats bullet list with name and description', () => {
+            const output = service.buildSkillsPrompt([
+                { name: 'sl', description: 'Semantic layer.', path: '/tmp/sl' },
+                { name: 'knowledge_capture', description: 'Wiki capture.', path: '/tmp/kc' },
+            ]);
+            expect(output).toContain('- sl: Semantic layer.');
+            expect(output).toContain('- knowledge_capture: Wiki capture.');
+            expect(output).toContain('Use the `load_skill` tool');
+        });
+        it('returns empty string when no skills are available', () => {
+            expect(service.buildSkillsPrompt([])).toBe('');
+        });
+        it('appends the async capture note for the research caller', () => {
+            const output = service.buildSkillsPrompt([{ name: 'sl', description: 'Semantic layer.', path: '/tmp/sl' }], 'research');
+            expect(output).toContain('captured automatically by a post-turn memory agent');
+            expect(output).toContain('Focus on answering, not on saving');
+        });
+        it('does not append the note for memory_agent caller', () => {
+            const output = service.buildSkillsPrompt([{ name: 'sl_capture', description: 'Capture skill.', path: '/tmp/cap' }], 'memory_agent');
+            expect(output).not.toContain('captured automatically by a post-turn memory agent');
+        });
+    });
+    describe('parseFrontmatter callers field', () => {
+        it('parses inline-array form', () => {
+            const frontmatter = service.parseFrontmatter('---\nname: x\ndescription: y\ncallers: [memory_agent]\n---\n');
+            expect(frontmatter.callers).toEqual(['memory_agent']);
+        });
+        it('parses comma-separated form', () => {
+            const frontmatter = service.parseFrontmatter('---\nname: x\ndescription: y\ncallers: research, memory_agent\n---\n');
+            expect(frontmatter.callers).toEqual(['research', 'memory_agent']);
+        });
+        it('returns undefined when callers is absent', () => {
+            const frontmatter = service.parseFrontmatter('---\nname: x\ndescription: y\n---\n');
+            expect(frontmatter.callers).toBeUndefined();
+        });
+        it('drops unknown caller names with a warning', () => {
+            const frontmatter = service.parseFrontmatter('---\nname: x\ndescription: y\ncallers: [bogus, memory_agent]\n---\n');
+            expect(frontmatter.callers).toEqual(['memory_agent']);
+        });
+        it('returns undefined when the value is empty', () => {
+            const frontmatter = service.parseFrontmatter('---\nname: x\ndescription: y\ncallers:\n---\n');
+            expect(frontmatter.callers).toBeUndefined();
+        });
+    });
+    describe('listSkills and getSkill caller filter', () => {
+        beforeEach(async () => {
+            await writeSkill('sl', '---\nname: sl\ndescription: Open to all.\n---\n\n# SL');
+            await writeSkill('sl_capture', '---\nname: sl_capture\ndescription: Memory-only capture skill.\ncallers: [memory_agent]\n---\n\n# Capture');
+            await writeSkill('knowledge_capture', '---\nname: knowledge_capture\ndescription: Wiki capture.\ncallers: [memory_agent]\n---\n\n# KC');
+            service = new SkillsRegistryService({ skillsDir: tempDir });
+        });
+        it('research caller sees only open skills', async () => {
+            const skills = await service.listSkills('research');
+            expect(skills.map((skill) => skill.name).sort()).toEqual(['sl']);
+        });
+        it('memory_agent caller sees memory-only and open skills', async () => {
+            const skills = await service.listSkills('memory_agent');
+            expect(skills.map((skill) => skill.name).sort()).toEqual(['knowledge_capture', 'sl', 'sl_capture']);
+        });
+        it('listSkills with names and caller intersects both filters', async () => {
+            const skills = await service.listSkills(['sl', 'sl_capture'], 'research');
+            expect(skills.map((skill) => skill.name)).toEqual(['sl']);
+        });
+        it('getSkill returns null for memory-only skill when caller is research', async () => {
+            const skill = await service.getSkill('sl_capture', 'research');
+            expect(skill).toBeNull();
+        });
+        it('getSkill returns the skill when caller has access', async () => {
+            const skill = await service.getSkill('sl_capture', 'memory_agent');
+            expect(skill?.name).toBe('sl_capture');
+        });
+        it('getSkill without caller returns the skill regardless of callers field', async () => {
+            const skill = await service.getSkill('sl_capture');
+            expect(skill?.name).toBe('sl_capture');
+        });
+    });
+    it('discovers skills from additional directories when the primary directory misses', async () => {
+        const extraDir = await mkdtemp(join(tmpdir(), 'skills-registry-extra-'));
+        try {
+            await mkdir(join(extraDir, 'knowledge_capture'), { recursive: true });
+            await writeFile(join(extraDir, 'knowledge_capture', 'SKILL.md'), [
+                '---',
+                'name: knowledge_capture',
+                'description: Packaged knowledge capture skill.',
+                'callers: [memory_agent]',
+                '---',
+                '',
+                '# Knowledge Capture',
+            ].join('\n'), 'utf-8');
+            service = new SkillsRegistryService({ skillsDir: tempDir, additionalSkillDirs: [extraDir] });
+            const skills = await service.listSkills(['knowledge_capture'], 'memory_agent');
+            expect(skills.map((skill) => skill.name)).toEqual(['knowledge_capture']);
+            expect(skills[0]?.path).toBe(join(extraDir, 'knowledge_capture'));
+        }
+        finally {
+            await rm(extraDir, { recursive: true, force: true });
+        }
+    });
+});

package/node_modules/@ktx/context/dist/sl/descriptions.d.ts

@@ -0,0 +1,14 @@
+declare const DESCRIPTION_SOURCES: readonly ["user", "ai", "dbt", "db"];
+type DescriptionSource = (typeof DESCRIPTION_SOURCES)[number];
+type DescriptionSources = Record<string, string>;
+interface DescriptionResolutionConfig {
+    priority: string[];
+}
+export declare const DEFAULT_PRIORITY: DescriptionSource[];
+/**
+ * Resolves which description to surface based on a priority list.
+ * Returns the first non-empty description matching a priority key,
+ * falling back to the first available value for unknown sources.
+ */
+export declare function resolveDescription(descriptions: DescriptionSources | undefined, config: DescriptionResolutionConfig): string | null;
+export {};

package/node_modules/@ktx/context/dist/sl/descriptions.js

@@ -0,0 +1,20 @@
+const DESCRIPTION_SOURCES = ['user', 'ai', 'dbt', 'db'];
+export const DEFAULT_PRIORITY = [...DESCRIPTION_SOURCES];
+/**
+ * Resolves which description to surface based on a priority list.
+ * Returns the first non-empty description matching a priority key,
+ * falling back to the first available value for unknown sources.
+ */
+export function resolveDescription(descriptions, config) {
+    if (!descriptions || Object.keys(descriptions).length === 0) {
+        return null;
+    }
+    for (const source of config.priority) {
+        const text = descriptions[source];
+        if (text) {
+            return text;
+        }
+    }
+    // Fallback: first available value (for unknown future sources)
+    return Object.values(descriptions).find(Boolean) ?? null;
+}

package/node_modules/@ktx/context/dist/sl/index.d.ts

@@ -0,0 +1,13 @@
+export type { SlValidationResult, SlValidatorPort } from './sl-validator.port.js';
+export type { SemanticLayerQueryExecutionResult, SemanticLayerQueryInput, SemanticLayerSource, SlDictionaryMatch, SlSearchLaneSummary, SlSearchMatchReason, SlSearchMetadata, } from './types.js';
+export type { KtxConnectionInfo, KtxQueryResult, SlConnectionCatalogPort, SlPythonPort, SlSourcesIndexPort, } from './ports.js';
+export { DEFAULT_PRIORITY, resolveDescription } from './descriptions.js';
+export { isOverlaySource, sourceDefinitionSchema, sourceOverlaySchema } from './schemas.js';
+export { composeOverlay, enrichColumnsFromManifest, findDanglingSegmentRefs, SemanticLayerService, } from './semantic-layer.service.js';
+export { loadLatestSlDictionaryEntries } from './sl-dictionary-profile.js';
+export type { SlDictionaryEntry } from './sl-dictionary-profile.js';
+export { buildSemanticLayerSourceSearchText, SlSearchService } from './sl-search.service.js';
+export { SqliteSlSourcesIndex, type SqliteSlSourcesIndexOptions } from './sqlite-sl-sources-index.js';
+export * from './local-sl.js';
+export * from './local-query.js';
+export * from './tools/index.js';