agent-world 0.11.1 → 0.12.0

package/dist/core/skill-registry.js

@@ -0,0 +1,369 @@
+/**
+ * Skill Registry - Singleton registry and synchronization for agent skills.
+ *
+ * Purpose:
+ * - Maintain one in-memory registry keyed by `skill_id`
+ * - Sync registry entries from discovered SKILL.md files in user/project roots
+ *
+ * Key Features:
+ * - Singleton module-level registry with exported helpers
+ * - Recursive SKILL.md discovery with deterministic ordering
+ * - Hash-based update checks using full SKILL.md content
+ * - Automatic initial sync on module load so core starts with up-to-date skills
+ * - Automatic pruning of entries whose files no longer exist
+ *
+ * Implementation Notes:
+ * - `skill_id` is sourced from front-matter `name`
+ * - `description` is sourced from front-matter `description`
+ * - `hash` is computed from full SKILL.md content (front matter + body)
+ * - Project roots are scanned after user roots, so later collisions always override earlier ones
+ *
+ * Recent Changes:
+ * - 2026-02-16: Default project-skill roots now resolve from active workspace env (`AGENT_WORLD_PROJECT_PATH`/`AGENT_WORLD_WORKSPACE_PATH`) before falling back to process cwd.
+ * - 2026-02-16: Added source-scope filtering helper so callers can include/exclude global or project skills when building system prompts.
+ * - 2026-02-14: Added `getSkillSourcePath` API and source-path tracking map for on-demand `SKILL.md` loading.
+ * - 2026-02-14: Added `~/.codex/skills` to default user skill roots for Codex-managed skills discovery.
+ * - 2026-02-14: Removed timestamp-gated update blocking so project-scope collisions always override user-scope entries when hashes differ.
+ * - 2026-02-14: Fixed skill collision precedence so project-root skills override user-root skills for the same `skill_id`.
+ * - 2026-02-14: Added `waitForInitialSkillSync` and startup sync tracking promise for deterministic core-load sync completion.
+ * - 2026-02-14: Added module-load auto-sync so each core load refreshes the skill registry.
+ * - 2026-02-14: Switched skill hash generation to use full SKILL.md content instead of metadata-only fields.
+ * - 2026-02-14: Switched registry metadata source to SKILL.md front matter (`name` + `description`).
+ * - 2026-02-14: Use front-matter `name` as canonical `skill_id`.
+ */
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import { homedir } from 'os';
+import * as path from 'path';
+function buildDefaultUserSkillRoots() {
+    return [
+        path.join(homedir(), '.agents', 'skills'),
+        path.join(homedir(), '.codex', 'skills'),
+    ];
+}
+function buildDefaultProjectSkillRoots() {
+    const envWorkspace = [
+        process.env.AGENT_WORLD_PROJECT_PATH,
+        process.env.AGENT_WORLD_WORKSPACE_PATH,
+        process.env.AGENT_WORLD_DATA_PATH,
+    ]
+        .map((value) => (typeof value === 'string' ? value.trim() : ''))
+        .find((value) => value.length > 0);
+    const projectRoot = envWorkspace || process.cwd();
+    return [path.join(projectRoot, '.agents', 'skills'), path.join(projectRoot, 'skills')];
+}
+function normalizeRoots(roots) {
+    const resolved = roots
+        .map((candidate) => candidate.trim())
+        .filter((candidate) => candidate.length > 0)
+        .map((candidate) => path.resolve(candidate));
+    return [...new Set(resolved)];
+}
+function isPathWithinRoot(candidatePath, rootPath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function createContentHash(content) {
+    return createHash('md5').update(content).digest('hex').slice(0, 8);
+}
+function normalizeFrontMatterValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return '';
+    }
+    const hasMatchingQuotes = (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"));
+    if (hasMatchingQuotes && trimmed.length >= 2) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function parseSkillFrontMatter(content) {
+    const frontMatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
+    if (!frontMatterMatch || !frontMatterMatch[1]) {
+        return {};
+    }
+    const lines = frontMatterMatch[1].split(/\r?\n/);
+    const metadata = {};
+    let currentMultilineKey = null;
+    let blockStyle = null;
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const keyValueMatch = rawLine.match(/^\s*([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+        if (keyValueMatch) {
+            const rawKey = keyValueMatch[1].trim();
+            const rawValue = keyValueMatch[2] ?? '';
+            if (rawKey !== 'name' && rawKey !== 'description') {
+                currentMultilineKey = null;
+                blockStyle = null;
+                continue;
+            }
+            if ((rawValue === '|' || rawValue === '>') && rawKey === 'description') {
+                metadata.description = '';
+                currentMultilineKey = rawKey;
+                blockStyle = rawValue === '|' ? 'literal' : 'folded';
+                continue;
+            }
+            metadata[rawKey] = normalizeFrontMatterValue(rawValue);
+            currentMultilineKey = null;
+            blockStyle = null;
+            continue;
+        }
+        if (!currentMultilineKey || currentMultilineKey !== 'description') {
+            continue;
+        }
+        if (!/^\s+/.test(rawLine)) {
+            currentMultilineKey = null;
+            blockStyle = null;
+            continue;
+        }
+        const chunk = rawLine.trim();
+        if (!chunk) {
+            continue;
+        }
+        if (blockStyle === 'literal') {
+            metadata.description = metadata.description
+                ? `${metadata.description}\n${chunk}`
+                : chunk;
+        }
+        else {
+            metadata.description = metadata.description
+                ? `${metadata.description} ${chunk}`
+                : chunk;
+        }
+    }
+    return metadata;
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readDirectoryEntries(directoryPath) {
+    try {
+        const entries = await fs.readdir(directoryPath, { withFileTypes: true });
+        return entries.sort((left, right) => left.name.localeCompare(right.name));
+    }
+    catch {
+        return [];
+    }
+}
+async function findSkillMarkdownFiles(rootPath) {
+    const output = [];
+    const queue = [rootPath];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+        const entries = await readDirectoryEntries(current);
+        for (const entry of entries) {
+            const absolutePath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(absolutePath);
+                continue;
+            }
+            if (entry.isFile() && entry.name === 'SKILL.md') {
+                output.push(absolutePath);
+            }
+        }
+    }
+    return output.sort((left, right) => left.localeCompare(right));
+}
+async function readSkillStats(skillFilePath) {
+    try {
+        return await fs.stat(skillFilePath);
+    }
+    catch {
+        return null;
+    }
+}
+async function discoverSkills(roots) {
+    const discovered = new Map();
+    for (const { rootPath, sourceScope } of roots) {
+        const exists = await pathExists(rootPath);
+        if (!exists) {
+            continue;
+        }
+        const skillFiles = await findSkillMarkdownFiles(rootPath);
+        for (const skillFilePath of skillFiles) {
+            const stats = await readSkillStats(skillFilePath);
+            if (!stats) {
+                continue;
+            }
+            discovered.set(skillFilePath, {
+                skillFilePath,
+                lastUpdated: stats.mtime.toISOString(),
+                sourceScope,
+            });
+        }
+    }
+    return discovered;
+}
+function createSkillRegistrySingleton() {
+    const registry = new Map();
+    const registrySourcePaths = new Map();
+    const registryScopes = new Map();
+    async function syncSkills(options = {}) {
+        const userRoots = normalizeRoots(options.userSkillRoots ?? buildDefaultUserSkillRoots());
+        const projectRoots = normalizeRoots(options.projectSkillRoots ?? buildDefaultProjectSkillRoots());
+        const roots = [
+            ...userRoots.map((rootPath) => ({ rootPath, sourceScope: 'global' })),
+            ...projectRoots.map((rootPath) => ({ rootPath, sourceScope: 'project' })),
+        ];
+        const discovered = await discoverSkills(roots);
+        const discoveredIds = new Set();
+        let added = 0;
+        let updated = 0;
+        let unchanged = 0;
+        const resolvedDiscovered = new Map();
+        for (const discoveredSkill of discovered.values()) {
+            let content;
+            try {
+                content = await fs.readFile(discoveredSkill.skillFilePath, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const metadata = parseSkillFrontMatter(content);
+            const skillId = (metadata.name ?? '').trim();
+            if (!skillId) {
+                continue;
+            }
+            const description = (metadata.description ?? '').trim();
+            resolvedDiscovered.set(skillId, {
+                description,
+                hash: createContentHash(content),
+                lastUpdated: discoveredSkill.lastUpdated,
+                skillFilePath: discoveredSkill.skillFilePath,
+                sourceScope: discoveredSkill.sourceScope,
+            });
+        }
+        for (const [skillId, discoveredSkill] of [...resolvedDiscovered.entries()].sort(([leftId], [rightId]) => leftId.localeCompare(rightId))) {
+            discoveredIds.add(skillId);
+            const existing = registry.get(skillId);
+            const nextHash = discoveredSkill.hash;
+            registrySourcePaths.set(skillId, discoveredSkill.skillFilePath);
+            registryScopes.set(skillId, discoveredSkill.sourceScope);
+            if (existing && existing.hash === nextHash) {
+                unchanged += 1;
+                continue;
+            }
+            registry.set(skillId, {
+                skill_id: skillId,
+                description: discoveredSkill.description,
+                hash: nextHash,
+                lastUpdated: discoveredSkill.lastUpdated,
+            });
+            if (existing) {
+                updated += 1;
+            }
+            else {
+                added += 1;
+            }
+        }
+        let removed = 0;
+        for (const skillId of [...registry.keys()]) {
+            if (!discoveredIds.has(skillId)) {
+                registry.delete(skillId);
+                registrySourcePaths.delete(skillId);
+                registryScopes.delete(skillId);
+                removed += 1;
+            }
+        }
+        return {
+            added,
+            updated,
+            removed,
+            unchanged,
+            total: registry.size,
+        };
+    }
+    function getSkills() {
+        return [...registry.values()].sort((left, right) => left.skill_id.localeCompare(right.skill_id));
+    }
+    function getSkill(skillId) {
+        return registry.get(skillId);
+    }
+    function getSkillSourcePath(skillId) {
+        return registrySourcePaths.get(skillId);
+    }
+    function getSkillSourceScope(skillId) {
+        return registryScopes.get(skillId);
+    }
+    function getSkillsForSystemPrompt(options = {}) {
+        const includeGlobal = options.includeGlobal !== false;
+        const includeProject = options.includeProject !== false;
+        if (!includeGlobal && !includeProject) {
+            return [];
+        }
+        const userRoots = normalizeRoots(options.userSkillRoots ?? buildDefaultUserSkillRoots());
+        const projectRoots = normalizeRoots(options.projectSkillRoots ?? buildDefaultProjectSkillRoots());
+        return [...registry.values()]
+            .filter((skill) => {
+            const sourcePath = registrySourcePaths.get(skill.skill_id);
+            const sourceScope = registryScopes.get(skill.skill_id);
+            if (sourceScope === 'project') {
+                return includeProject;
+            }
+            if (sourceScope === 'global') {
+                return includeGlobal;
+            }
+            if (!sourcePath) {
+                return includeGlobal || includeProject;
+            }
+            const resolvedSourcePath = path.resolve(sourcePath);
+            const isProjectSkill = projectRoots.some((rootPath) => isPathWithinRoot(resolvedSourcePath, rootPath));
+            if (isProjectSkill) {
+                return includeProject;
+            }
+            const isGlobalSkill = userRoots.some((rootPath) => isPathWithinRoot(resolvedSourcePath, rootPath));
+            if (isGlobalSkill) {
+                return includeGlobal;
+            }
+            return includeGlobal && includeProject;
+        })
+            .sort((left, right) => left.skill_id.localeCompare(right.skill_id));
+    }
+    function clearSkillsForTests() {
+        registry.clear();
+        registrySourcePaths.clear();
+        registryScopes.clear();
+    }
+    return { syncSkills, getSkills, getSkill, getSkillSourcePath, getSkillSourceScope, getSkillsForSystemPrompt, clearSkillsForTests };
+}
+export const skillRegistry = createSkillRegistrySingleton();
+export const syncSkills = skillRegistry.syncSkills;
+export const getSkills = skillRegistry.getSkills;
+export const getSkill = skillRegistry.getSkill;
+export const getSkillSourcePath = skillRegistry.getSkillSourcePath;
+export const getSkillSourceScope = skillRegistry.getSkillSourceScope;
+export const getSkillsForSystemPrompt = skillRegistry.getSkillsForSystemPrompt;
+export const clearSkillsForTests = skillRegistry.clearSkillsForTests;
+const EMPTY_SYNC_RESULT = {
+    added: 0,
+    updated: 0,
+    removed: 0,
+    unchanged: 0,
+    total: 0,
+};
+let initialSkillSyncPromise = null;
+function ensureInitialSkillSyncStarted() {
+    if (!initialSkillSyncPromise) {
+        initialSkillSyncPromise = syncSkills().catch(() => EMPTY_SYNC_RESULT);
+    }
+    return initialSkillSyncPromise;
+}
+export function waitForInitialSkillSync() {
+    return ensureInitialSkillSyncStarted();
+}
+// Keep the registry warm when core loads, without breaking module import flows on sync errors.
+void ensureInitialSkillSyncStarted();
+//# sourceMappingURL=skill-registry.js.map

package/dist/core/skill-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-registry.js","sourceRoot":"","sources":["../../core/skill-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/skill-script-runner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Skill Script Runner Module - Dedicated executor for skill-bundled scripts
+ *
+ * Purpose:
+ * Provides a sandboxed, path-guarded script executor for files stored under
+ * `{world-dir}/skills/{skill-name}/scripts/`. This is the ONLY entry point
+ * for skill script execution — the generic `shell-cmd-tool.ts` must NEVER
+ * be used for skill scripts.
+ *
+ * Features:
+ * - Strict path guards: resolve + verify target stays within the skill's `scripts/` directory
+ * - Runtime sandbox permissions: allowlist of allowed interpreters
+ * - Execution controls: configurable timeout, max output size, exit code capture
+ * - stdout/stderr capture with size limits
+ * - Explicit error handling with structured results
+ *
+ * Notes:
+ * - This module does NOT use `shell-cmd-tool.ts` — it is a separate executor
+ * - Scripts are executed via child_process.spawn with explicit interpreter
+ * - Path traversal is prevented by resolving + verifying all paths
+ * - Only scripts under `{skill-dir}/scripts/` are allowed to execute
+ *
+ * Recent Changes:
+ * - 2026-02-09: Initial implementation for world-level skills system
+ */
+/** Result of a skill script execution */
+export interface SkillScriptResult {
+    /** Exit code of the process (null if killed/timed out) */
+    exitCode: number | null;
+    /** Signal that terminated the process, if any */
+    signal: string | null;
+    /** Captured stdout (truncated to maxOutputSize) */
+    stdout: string;
+    /** Captured stderr (truncated to maxOutputSize) */
+    stderr: string;
+    /** Whether execution was killed due to timeout */
+    timedOut: boolean;
+    /** Whether output was truncated */
+    truncated: boolean;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/** Options for script execution */
+export interface SkillScriptOptions {
+    /** Timeout in milliseconds (default: 30000 = 30 seconds) */
+    timeout?: number;
+    /** Maximum output size in bytes for stdout/stderr each (default: 65536 = 64KB) */
+    maxOutputSize?: number;
+    /** Environment variables to pass to the script */
+    env?: Record<string, string>;
+    /** Arguments to pass to the script */
+    args?: string[];
+}
+/**
+ * Build the scripts directory path for a skill.
+ */
+export declare function getSkillScriptsDir(rootPath: string, worldId: string, skillName: string): string;
+/**
+ * Resolve and validate that a script path stays within the skill's scripts/ directory.
+ * Throws if the resolved path escapes the boundary.
+ */
+export declare function resolveAndGuardScriptPath(scriptsDir: string, scriptName: string): string;
+/**
+ * Determine the interpreter to use for a script based on its file extension.
+ * Returns null if the extension is not in the allowlist.
+ */
+export declare function detectInterpreter(scriptPath: string): {
+    command: string;
+    extraArgs: string[];
+} | null;
+/**
+ * Execute a skill script with sandbox/permission guards.
+ *
+ * This function:
+ * 1. Validates the script path stays within the skill's scripts/ directory
+ * 2. Verifies the script file exists
+ * 3. Detects the appropriate interpreter from file extension
+ * 4. Executes with timeout, output size limits, and environment isolation
+ * 5. Captures stdout, stderr, exit code, and timing
+ *
+ * @param rootPath - Root storage path (e.g., ~/agent-world)
+ * @param worldId - World identifier
+ * @param skillName - Skill name (kebab-case)
+ * @param scriptName - Script filename (e.g., "run.sh", "analyze.py")
+ * @param options - Execution options (timeout, max output, env, args)
+ * @returns Structured execution result
+ */
+export declare function runSkillScript(rootPath: string, worldId: string, skillName: string, scriptName: string, options?: SkillScriptOptions): Promise<SkillScriptResult>;
+//# sourceMappingURL=skill-script-runner.d.ts.map

package/dist/core/skill-script-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-script-runner.d.ts","sourceRoot":"","sources":["../../core/skill-script-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAaH,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iDAAiD;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AA2CD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/F;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,CA0BR;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAUrG;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAkD5B"}