salmon-loop 0.2.3 → 0.2.16

package/dist/core/skills/bridge.js

@@ -1,14 +1,57 @@
 import { z } from 'zod';
-import { MicroTaskRunner } from './runtime/MicroTaskRunner.js';
+import { tryGetLogger } from '../observability/logger.js';
+import { emitSkillAuditEvent, generateSkillTraceId, hashSkillArgs } from './audit.js';
+import { getSkillFeatureFlags } from './feature-flags.js';
+import { executeSkill } from './runtime/SkillRunner.js';
 /**
- * Bridges a Skill into a ToolSpec compatible with the standard tool registry.
+ * Check whether the bridge execution path kill-switch is active.
+ *
+ * Delegates to the centralized {@link getSkillFeatureFlags} module which
+ * reads `SALMONLOOP_DISABLE_BRIDGE_SKILL_EXEC` from the environment.
+ *
+ *   - 'true' or '1'  → bridge disabled (kill-switch ON)
+ *   - 'false' or '0' → bridge enabled  (kill-switch OFF)
+ *   - not set         → disabled in non-dev, enabled in development
+ *
+ * @see Requirements 9.4, 11.4
  */
-export function skillToToolSpec(skill) {
+export function isBridgeSkillExecDisabled() {
+    return getSkillFeatureFlags().bridgeDisabled;
+}
+function isLazySource(source) {
+    return 'entry' in source && 'loader' in source;
+}
+/**
+ * Bridges a Skill (or catalog entry) into a ToolSpec compatible with the
+ * standard tool registry.
+ *
+ * When given a catalog entry + loader, the executor performs Tier 2 activation
+ * on first invocation (progressive disclosure). When given a full Skill, it
+ * executes immediately.
+ *
+ * The executor delegates to executeSkill() which routes all shell commands
+ * through ToolRouter governance (Registry → Validation → Policy → Auth).
+ *
+ * When the kill-switch env var `SALMONLOOP_DISABLE_BRIDGE_SKILL_EXEC` is
+ * set to 'true' or '1', the executor returns a DENIED result and emits
+ * a SKILL_EXECUTION_DENIED audit event instead of executing the skill.
+ *
+ * @param source - Either a full {@link Skill} or a `{ entry, loader }` pair
+ *   for lazy activation.
+ * @param routerBox - A mutable box whose `.router` field will be populated
+ *   after the ToolRouter is created. The executor reads it lazily at call
+ *   time, so it is safe to pass an initially-null box.
+ */
+export function skillToToolSpec(source, routerBox) {
+    const skillId = isLazySource(source) ? source.entry.id : source.id;
+    const description = isLazySource(source) ? source.entry.description : source.metadata.description;
+    // Cache for lazily activated skill (Tier 2)
+    let activatedSkill = isLazySource(source) ? null : source;
     return {
-        name: skill.id,
+        name: skillId,
         source: 'plugin',
         intent: 'AGENT',
-        description: skill.metadata.description,
+        description,
         riskLevel: 'medium',
         sideEffects: ['process', 'fs_read'],
         concurrency: 'serial_only',
@@ -21,8 +64,42 @@ export function skillToToolSpec(skill) {
             status: z.string(),
         }),
         executor: async (input, ctx) => {
-            const runner = new MicroTaskRunner(skill);
-            const result = await runner.execute({ args: input.args || '' }, ctx);
+            if (isBridgeSkillExecDisabled()) {
+                const traceId = generateSkillTraceId(skillId);
+                const argsHash = hashSkillArgs(input.args || '');
+                emitSkillAuditEvent({
+                    type: 'SKILL_EXECUTION_DENIED',
+                    skillId,
+                    route: 'tool-bridge',
+                    runnerClass: 'MicroTaskRunner',
+                    commandCount: 0,
+                    authorizationMode: 'blocking',
+                    argsHash,
+                    traceId,
+                    denyReason: 'BRIDGE_KILL_SWITCH',
+                    denySource: 'env:SALMONLOOP_DISABLE_BRIDGE_SKILL_EXEC',
+                });
+                const logger = tryGetLogger();
+                logger?.warn(`Bridge skill execution denied by kill-switch for skill "${skillId}" (traceId=${traceId})`);
+                return { prompt: '', status: 'DENIED' };
+            }
+            // Tier 2 activation: load full skill content on first invocation
+            if (!activatedSkill) {
+                const lazySource = source;
+                activatedSkill = await lazySource.loader.activateSkill(lazySource.entry.id);
+            }
+            // Lazily read the router from the box — it is populated after filtering.
+            const toolRouter = routerBox.router;
+            if (!toolRouter) {
+                throw new Error(`ToolRouter not yet initialized for skill "${skillId}"`);
+            }
+            const result = await executeSkill({
+                skill: activatedSkill,
+                argsText: input.args || '',
+                toolRouter,
+                toolCtx: ctx,
+                route: 'tool-bridge',
+            });
             return {
                 prompt: result.injectedPrompt,
                 status: result.status,

package/dist/core/skills/discovery.js

@@ -0,0 +1,94 @@
+import { text } from '../../locales/index.js';
+import { getLogger } from '../observability/logger.js';
+/**
+ * Check whether a file path matches a glob-like pattern.
+ *
+ * Supports:
+ * - `**` to match any number of path segments
+ * - `*` to match any characters within a single path segment
+ * - Literal path matching
+ *
+ * @param filePath - The file path to test (forward-slash normalized)
+ * @param pattern - The glob pattern to match against
+ * @returns true if the file path matches the pattern
+ */
+export function matchGlob(filePath, pattern) {
+    // Normalize separators to forward slash for consistent matching
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const normalizedPattern = pattern.replace(/\\/g, '/');
+    // Build regex from glob pattern character by character
+    let regexStr = '';
+    let i = 0;
+    while (i < normalizedPattern.length) {
+        const ch = normalizedPattern[i];
+        if (ch === '*' && normalizedPattern[i + 1] === '*') {
+            // ** — match any number of path segments (including zero)
+            // Consume optional trailing slash: **/ matches zero-or-more dirs
+            i += 2;
+            if (normalizedPattern[i] === '/') {
+                i++;
+                // `**/` matches zero or more directory segments
+                regexStr += '(?:.+/)?';
+            }
+            else {
+                // `**` at end matches everything
+                regexStr += '.*';
+            }
+        }
+        else if (ch === '*') {
+            // * — match any characters except /
+            regexStr += '[^/]*';
+            i++;
+        }
+        else {
+            // Escape regex special characters for literal match
+            regexStr += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            i++;
+        }
+    }
+    const regex = new RegExp(`^${regexStr}$`);
+    return regex.test(normalizedPath);
+}
+/**
+ * Signal-based skill discovery watcher.
+ *
+ * Does NOT use fs.watch — instead provides methods that can be called
+ * when file operations happen. The caller handles the event source.
+ *
+ * Supports:
+ * - Re-scanning search paths for newly added skill directories (Requirement 7.1)
+ *
+ * @see Requirements 7.1, 7.2
+ */
+export class SkillDiscoveryWatcher {
+    /** Known skill ids from the last catalog snapshot. */
+    knownIds = new Set();
+    constructor(initialCatalog) {
+        for (const entry of initialCatalog) {
+            this.knownIds.add(entry.id);
+        }
+    }
+    /**
+     * Accept a refreshed catalog and return entries that are new
+     * (not previously known).
+     *
+     * Call this after re-scanning search paths (e.g. via SkillLoader.loadCatalog())
+     * when a file-operation signal indicates new skill directories may exist.
+     *
+     * @param refreshedCatalog - The full catalog from a fresh scan
+     * @returns Newly discovered catalog entries not in the previous snapshot
+     * @see Requirement 7.1
+     */
+    refreshCatalog(refreshedCatalog) {
+        const newEntries = [];
+        for (const entry of refreshedCatalog) {
+            if (!this.knownIds.has(entry.id)) {
+                newEntries.push(entry);
+                this.knownIds.add(entry.id);
+                getLogger().info(text.skills.newSkillDiscovered(entry.id, entry.location));
+            }
+        }
+        return newEntries;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/core/skills/feature-flags.js

@@ -0,0 +1,52 @@
+/**
+ * Centralized feature flags for the skills subsystem.
+ *
+ * Provides rollout control over bridge execution.
+ *
+ * @see Requirements 11.4
+ */
+import { tryGetLogger } from '../observability/logger.js';
+// ---------------------------------------------------------------------------
+// Env-var helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a boolean-ish env var value.
+ * Returns `true` for 'true'/'1', `false` for 'false'/'0', or the
+ * provided `fallback` when the value is undefined/empty.
+ */
+function parseBoolEnv(value, fallback) {
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    return fallback;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read all skill-related feature flags from environment variables.
+ *
+ * The function is intentionally pure (no caching) so that tests can
+ * manipulate `process.env` between calls and observe the effect.
+ *
+ * @returns A snapshot of the current feature flag values
+ * @see Requirements 11.4
+ */
+export function getSkillFeatureFlags() {
+    const bridgeDefault = process.env.NODE_ENV !== 'development';
+    return {
+        bridgeDisabled: parseBoolEnv(process.env.SALMONLOOP_DISABLE_BRIDGE_SKILL_EXEC, bridgeDefault),
+    };
+}
+/**
+ * Log the current feature flag values at debug level.
+ *
+ * Useful at startup to record which flags are active for diagnostics.
+ */
+export function logSkillFeatureFlags() {
+    const flags = getSkillFeatureFlags();
+    const logger = tryGetLogger();
+    logger?.debug(`Skill feature flags: bridgeDisabled=${flags.bridgeDisabled}`);
+}
+//# sourceMappingURL=feature-flags.js.map

package/dist/core/skills/index.js

@@ -3,6 +3,6 @@ export * from './loader.js';
 export * from './parser.js';
 export * from './strategy.js';
 export * from './bridge.js';
-export { MicroTaskRunner } from './runtime/MicroTaskRunner.js';
+export * from './feature-flags.js';
 export * from './runtime/SkillRunner.js';
 //# sourceMappingURL=index.js.map

package/dist/core/skills/loader.js

@@ -1,71 +1,246 @@
 import os from 'node:os';
 import path from 'node:path';
+import { text } from '../../locales/index.js';
 import { syncFs as fs } from '../adapters/fs/node-fs.js';
-import { getLogger } from '../observability/logger.js';
+import { tryGetLogger } from '../observability/logger.js';
 import { SkillParser } from './parser.js';
+/**
+ * Safe logger accessor that never throws when the logger is not yet initialized.
+ *
+ * Falls back to a no-op stub so that loader code can run in test environments
+ * or early startup paths where the global logger has not been set.
+ */
+function safeLogger() {
+    return (tryGetLogger() ?? {
+        error: (..._args) => { },
+        warn: (..._args) => { },
+        info: (..._args) => { },
+        debug: (..._args) => { },
+        audit: (..._args) => { },
+    });
+}
 export class SkillLoader {
     options;
+    /**
+     * Format the skill catalog into a model-consumable disclosure block.
+     *
+     * Pure data contract: accepts catalog + optional context paths, returns string.
+     * No dependency on session or prompt layer.
+     *
+     * @param catalog - Array of SkillCatalogEntry from loadCatalog()
+     * @returns Formatted string with preamble + skill entries, or empty string if
+     *   no disclosable skills
+     * @see Requirements 4.1, 4.6
+     */
+    static formatCatalogDisclosure(catalog) {
+        if (catalog.length === 0) {
+            return '';
+        }
+        const preamble = `## Available Skills\n\n${text.skills.catalogDisclosurePreamble}`;
+        const entries = catalog
+            .map((entry) => `- **${entry.name}**: ${entry.description}\n  Location: ${entry.location}`)
+            .join('\n\n');
+        return `${preamble}\n\n${entries}\n`;
+    }
+    /** Cache of fully activated skills (Tier 2). */
+    activated = new Map();
+    /** Cached catalog entries from the last loadCatalog() call. */
+    catalogCache = null;
     constructor(options) {
         this.options = options;
     }
-    async initialize() {
-        const inventory = [];
+    /**
+     * Tier 2: Activate a skill by id — load full SKILL.md content on demand.
+     *
+     * Looks up the skill in the catalog (loading it first if necessary),
+     * reads the full file content, parses it with {@link SkillParser.parse},
+     * and caches the result. Subsequent calls for the same id return the
+     * cached {@link Skill} without re-reading the file.
+     *
+     * @param id - The skill identifier (must match a catalog entry)
+     * @returns The fully loaded {@link Skill} with instructions
+     * @throws Error if the skill id is not found in the catalog
+     * @see Requirements 6.2, 6.4
+     */
+    async activateSkill(id) {
+        // Return cached activation if already loaded
+        const cached = this.activated.get(id);
+        if (cached) {
+            return cached;
+        }
+        // Ensure catalog is available
+        if (!this.catalogCache) {
+            this.catalogCache = await this.loadCatalog();
+        }
+        const entry = this.catalogCache.find((e) => e.id === id);
+        if (!entry) {
+            throw new Error(text.skills.skillNotFoundInCatalog(id));
+        }
+        // Read full content and parse with SkillParser
+        const content = fs.readFileSync(entry.location, 'utf-8');
+        const skill = SkillParser.parse(content, entry.location);
+        this.activated.set(id, skill);
+        safeLogger().info(text.skills.skillActivated(id));
+        return skill;
+    }
+    /**
+     * Tier 1: Load a lightweight catalog of all discoverable skills.
+     *
+     * Parses only YAML frontmatter (name + description + location) without
+     * loading full instruction content. Keeps startup context cost at
+     * approximately 50-100 tokens per skill.
+     *
+     * Uses the same search path priority and conflict resolution as
+     * {@link initialize}, but avoids reading instruction bodies.
+     *
+     * @returns Array of {@link SkillCatalogEntry} in discovery priority order
+     * @see Requirements 6.1, 6.3
+     */
+    async loadCatalog() {
+        const catalog = [];
         const seen = new Map();
         for (const target of this.buildSearchPaths()) {
             if (!fs.existsSync(target.path))
                 continue;
+            const scope = this.labelToScope(target.label);
             const entries = fs.readdirSync(target.path, { withFileTypes: true });
             for (const entry of entries) {
-                let skillFile = null;
-                if (entry.isDirectory()) {
-                    skillFile = path.join(target.path, entry.name, 'SKILL.md');
+                if (!entry.isDirectory())
+                    continue;
+                const skillFile = path.join(target.path, entry.name, 'SKILL.md');
+                if (!skillFile || !fs.existsSync(skillFile))
+                    continue;
+                try {
+                    const content = fs.readFileSync(skillFile, 'utf-8');
+                    const catalogEntry = SkillParser.parseFrontmatterOnly(content, skillFile, scope);
+                    if (seen.has(catalogEntry.id)) {
+                        const firstSource = seen.get(catalogEntry.id);
+                        safeLogger().warn(`Duplicate skill ${catalogEntry.id} found in ${skillFile}; already loaded from ${firstSource}`);
+                        safeLogger().audit('SKILL_DUPLICATE_SKIPPED', {
+                            skillId: catalogEntry.id,
+                            skippedPath: skillFile,
+                            firstSource,
+                            reason: 'first_win_conflict_resolution',
+                        }, { source: 'skill-loader', severity: 'low', scope: 'repo' });
+                        continue;
+                    }
+                    seen.set(catalogEntry.id, `${target.label}:${skillFile}`);
+                    catalog.push(catalogEntry);
                 }
-                else if (entry.name.endsWith('.md')) {
-                    skillFile = path.join(target.path, entry.name);
+                catch (err) {
+                    safeLogger().error(`Failed to load skill catalog entry at ${skillFile}: ${err instanceof Error ? err.message : String(err)}`);
                 }
+            }
+        }
+        this.catalogCache = catalog;
+        return catalog;
+    }
+    async initialize() {
+        return this.loadSkillsFromPaths();
+    }
+    /**
+     * Synchronous variant of {@link initialize} for callers that cannot await.
+     *
+     * Safe because all underlying I/O uses `syncFs` (synchronous fs operations).
+     * Used by tool-name discovery for tab completion.
+     */
+    initializeSync() {
+        return this.loadSkillsFromPaths();
+    }
+    loadSkillsFromPaths() {
+        const inventory = [];
+        const seen = new Map();
+        for (const target of this.buildSearchPaths()) {
+            if (!fs.existsSync(target.path))
+                continue;
+            const entries = fs.readdirSync(target.path, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const skillFile = path.join(target.path, entry.name, 'SKILL.md');
                 if (!skillFile || !fs.existsSync(skillFile))
                     continue;
                 try {
                     const content = fs.readFileSync(skillFile, 'utf-8');
                     const skill = SkillParser.parse(content, skillFile);
                     if (seen.has(skill.id)) {
-                        getLogger().warn(`Duplicate skill ${skill.id} found in ${skillFile}; already loaded from ${seen.get(skill.id)}`);
+                        const firstSource = seen.get(skill.id);
+                        safeLogger().warn(`Duplicate skill ${skill.id} found in ${skillFile}; already loaded from ${firstSource}`);
+                        safeLogger().audit('SKILL_DUPLICATE_SKIPPED', {
+                            skillId: skill.id,
+                            skippedPath: skillFile,
+                            firstSource,
+                            reason: 'first_win_conflict_resolution',
+                        }, { source: 'skill-loader', severity: 'low', scope: 'repo' });
                         continue;
                     }
                     seen.set(skill.id, `${target.label}:${skillFile}`);
                     inventory.push(skill);
                 }
                 catch (err) {
-                    getLogger().error(`Failed to load skill at ${skillFile}: ${err instanceof Error ? err.message : String(err)}`);
+                    safeLogger().error(`Failed to load skill at ${skillFile}: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
         }
         return inventory;
     }
+    /**
+     * Derive the catalog scope from a search path label.
+     *
+     * Labels follow the pattern `prefix:path` where prefix is one of:
+     * - `config` → 'config' scope (extra paths from skills.json)
+     * - `repo` → 'repo' scope (repo-level directories)
+     * - `user` → 'user' scope (user home directories)
+     * - `repo` / others → 'repo' scope
+     */
+    labelToScope(label) {
+        if (label.startsWith('config:'))
+            return 'config';
+        if (label.startsWith('user:'))
+            return 'user';
+        return 'repo';
+    }
+    /**
+     * Build the ordered list of skill search paths.
+     *
+     * Priority (high → low):
+     *   1. Config extra paths (from skills.json discovery.paths)
+     *   2. {repoRoot}/.salmonloop/skills
+     *   3. {repoRoot}/.agents/skills        (cross-client interop)
+     *   4. ~/.salmonloop/skills
+     *   5. ~/.agents/skills                 (cross-client interop)
+     *
+     * First-win conflict resolution: when two skills share the same name,
+     * the one from the higher-priority path wins and a warning is logged
+     * (handled in initialize()).
+     */
     buildSearchPaths() {
         const paths = [];
+        // 1. Config extra paths (highest priority)
         const extra = this.options.extraPaths ?? [];
         for (const extraPath of extra) {
             paths.push({ path: extraPath, label: `config:${extraPath}` });
         }
+        // 2. Repo-level .salmonloop/skills
         paths.push({
             path: path.join(this.options.repoRoot, '.salmonloop', 'skills'),
             label: 'repo:.salmonloop/skills',
         });
+        // 3. Repo-level .agents/skills (cross-client interop)
+        paths.push({
+            path: path.join(this.options.repoRoot, '.agents', 'skills'),
+            label: 'repo:.agents/skills',
+        });
+        // 4. User-level ~/.salmonloop/skills
         paths.push({
             path: path.join(os.homedir(), '.salmonloop', 'skills'),
             label: 'user:~/.salmonloop/skills',
         });
-        if (this.options.useDefaults ?? true) {
-            paths.push({
-                path: path.join(os.homedir(), '.claude', 'skills'),
-                label: 'compat:~/.claude/skills',
-            });
-            paths.push({
-                path: path.join(this.options.repoRoot, '.claude', 'skills'),
-                label: 'compat:.claude/skills',
-            });
-        }
+        // 5. User-level ~/.agents/skills (cross-client interop)
+        paths.push({
+            path: path.join(os.homedir(), '.agents', 'skills'),
+            label: 'user:~/.agents/skills',
+        });
         const deduped = [];
         const seen = new Set();
         for (const entry of paths) {