@amalgm/agents 0.1.0 → 0.1.1

package/PURPOSE.md

@@ -11,6 +11,8 @@ remain usable without Chat or Amalgm Engine.
 Engine composes Agents with harnesses, credentials, Toolbox, files, Realtime,
 and UI. This package stores references to those products and delegates
 execution to an injected driver; it does not duplicate their state.
+It also discovers installed agent skills across the canonical project and
+harness roots so every transport presents the same available skill catalog.
 
 ## Primitives
 

package/README.md

@@ -71,6 +71,18 @@ session stays pinned to that revision even after the agent is edited.
 | MCP | `@amalgm/agents/mcp`, `amalgm-agents-mcp` | Agent CRUD and agent-to-agent calls |
 | Skill | `skills/amalgm-agents` | Minimal workflow over the Agents tools |
 
+Installed skills are available from the REST surface without introducing a
+second registry:
+
+```bash
+curl http://127.0.0.1:PORT/skills
+curl 'http://127.0.0.1:PORT/skills/list?include_content=true'
+```
+
+The scanner reads the same canonical project, shared, Codex, Claude Code, and
+OpenCode roots as Engine. Hosts inject `skillRoots` when they need a selected
+project or an isolated home.
+
 ## CLI
 
 ```bash

package/dist/http/server.js

@@ -4,6 +4,7 @@ import { asAgentError } from '../errors.js';
 import { routeAgents } from './agent-routes.js';
 import { guardRequest, readJson, sendJson } from './request.js';
 import { routeSessions } from './session-routes.js';
+import { routeSkills } from './skill-routes.js';
 import { streamEvents } from './stream.js';
 export function createRestServer(options = {}) {
     const agents = options.agents || new Agents(options);
@@ -37,22 +38,25 @@ export function createRestServer(options = {}) {
             return;
         }
         const path = url.pathname.split('/').filter(Boolean);
-        if (path.shift() !== 'v1') {
-            sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });
-            return;
-        }
-        if (path[0] === 'sessions' && path[2] === 'events' && path[3] === 'stream' && request.method === 'GET') {
-            streamEvents(agents, path[1] || '', request, response, Number(url.searchParams.get('after') || 0));
-            return;
-        }
         const context = {
             agents,
             method: request.method || 'GET',
             path,
             url,
+            skillRoots: options.skillRoots || {},
             body: () => readJson(request, bodyLimit),
             json: (status, value) => sendJson(response, status, value),
         };
+        if (await routeSkills(context))
+            return;
+        if (path.shift() !== 'v1') {
+            sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });
+            return;
+        }
+        if (path[0] === 'sessions' && path[2] === 'events' && path[3] === 'stream' && request.method === 'GET') {
+            streamEvents(agents, path[1] || '', request, response, Number(url.searchParams.get('after') || 0));
+            return;
+        }
         if (await routeAgents(context) || await routeSessions(context))
             return;
         sendJson(response, 404, { error: { code: 'not_found', message: 'Route not found.' } });

package/dist/http/skill-routes.d.ts

@@ -0,0 +1,3 @@
+/** HTTP laws from Engine `server/routes/agents.js` and `skills/rest.js`. */
+import type { RouteContext } from '../http-types.js';
+export declare function routeSkills(context: RouteContext): Promise<boolean>;

package/dist/http/skill-routes.js

@@ -0,0 +1,25 @@
+/** HTTP laws from Engine `server/routes/agents.js` and `skills/rest.js`. */
+import { scanInstalledSkills } from '../skills/scanner.js';
+function truthy(value) {
+    return value === '1' || value?.toLowerCase() === 'true';
+}
+export async function routeSkills(context) {
+    const [resource, action] = context.path;
+    if (resource !== 'skills')
+        return false;
+    const includeContent = truthy(context.url.searchParams.get('include_content'));
+    if ((!action || action === 'list') && context.method === 'GET') {
+        context.json(200, {
+            skills: scanInstalledSkills({ ...context.skillRoots, includeContent }).skills,
+        });
+        return true;
+    }
+    if (action === 'refresh' && context.method === 'POST') {
+        context.json(200, {
+            ok: true,
+            skills: scanInstalledSkills(context.skillRoots).skills,
+        });
+        return true;
+    }
+    return false;
+}

package/dist/http-types.d.ts

@@ -2,10 +2,12 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import type { Agents } from './agents.js';
 import type { AgentsOptions } from './types.js';
+import type { SkillRootOptions } from './skills/roots.js';
 export interface RestServerOptions extends AgentsOptions {
     agents?: Agents;
     token?: string;
     bodyLimitBytes?: number;
+    skillRoots?: SkillRootOptions;
 }
 export interface RestServer {
     agents: Agents;
@@ -18,6 +20,7 @@ export interface RouteContext {
     method: string;
     path: string[];
     url: URL;
+    skillRoots: SkillRootOptions;
     body(): Promise<Record<string, unknown>>;
     json(status: number, value: unknown): void;
 }

package/dist/index.d.ts

@@ -4,3 +4,7 @@ export { defineDriver, driverSpecifiers, loadDriverModules } from './drivers.js'
 export { definitionHash, normalizeDefinition, patchDefinition } from './definition.js';
 export { messageText, normalizeMessage } from './messages.js';
 export type * from './types.js';
+export { buildCanonicalSkillRoots, classifySkillRoot } from './skills/roots.js';
+export type { SkillRootClassification, SkillRootOptions } from './skills/roots.js';
+export { parseSkillFrontmatter, scanInstalledSkills } from './skills/scanner.js';
+export type { InstalledSkill, SkillScanOptions } from './skills/scanner.js';

package/dist/index.js

@@ -3,3 +3,5 @@ export { AgentError, asAgentError } from './errors.js';
 export { defineDriver, driverSpecifiers, loadDriverModules } from './drivers.js';
 export { definitionHash, normalizeDefinition, patchDefinition } from './definition.js';
 export { messageText, normalizeMessage } from './messages.js';
+export { buildCanonicalSkillRoots, classifySkillRoot } from './skills/roots.js';
+export { parseSkillFrontmatter, scanInstalledSkills } from './skills/scanner.js';

package/dist/mcp/server.js

@@ -16,7 +16,7 @@ export function createMcpServer(options = {}) {
             return {
                 protocolVersion: message.params?.protocolVersion || '2024-11-05',
                 capabilities: { tools: { listChanged: false } },
-                serverInfo: { name: 'amalgm-agents', version: '0.1.0' },
+                serverInfo: { name: 'amalgm-agents', version: '0.1.1' },
             };
         }
         if (message.method === 'ping')

package/dist/skills/roots.d.ts

@@ -0,0 +1,16 @@
+/** Canonical installed-skill roots from Engine `skills/roots.js`. */
+export interface SkillRootOptions {
+    selectedCwd?: string;
+    homeDir?: string;
+    codexHome?: string;
+    claudeConfigDir?: string;
+}
+export interface SkillRootClassification {
+    provider: 'shared' | 'codex' | 'claude_code' | 'opencode';
+    scope: 'project' | 'global';
+    rootLabel: string;
+}
+export declare function normalizePath(value: unknown): string;
+export declare function buildCanonicalSkillRoots(options?: SkillRootOptions): string[];
+export declare function isCodexWorktreeRoot(rootPath: string, options?: SkillRootOptions): boolean;
+export declare function classifySkillRoot(rootPath: string, options?: SkillRootOptions): SkillRootClassification;

package/dist/skills/roots.js

@@ -0,0 +1,105 @@
+/** Canonical installed-skill roots from Engine `skills/roots.js`. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function normalizePath(value) {
+    return typeof value === 'string' && value.trim() ? path.resolve(value.trim()) : '';
+}
+function existingDirectory(value) {
+    const directory = normalizePath(value);
+    if (!directory)
+        return '';
+    try {
+        return fs.statSync(directory).isDirectory() ? directory : '';
+    }
+    catch {
+        return '';
+    }
+}
+function uniquePaths(values) {
+    return [...new Set(values.map(normalizePath).filter(Boolean))];
+}
+function nativeHome(options) {
+    return normalizePath(options.homeDir || process.env.AMALGM_NATIVE_HOME || os.homedir());
+}
+function projectRoots(selectedCwd) {
+    const roots = [];
+    let current = existingDirectory(selectedCwd);
+    while (current) {
+        const root = existingDirectory(path.join(current, '.agents', 'skills'));
+        if (root)
+            roots.push(root);
+        const parent = path.dirname(current);
+        if (!parent || parent === current)
+            break;
+        current = parent;
+    }
+    return roots;
+}
+function worktreeRoots(home) {
+    const worktrees = existingDirectory(path.join(home, '.codex', 'worktrees'));
+    if (!worktrees)
+        return [];
+    try {
+        return fs.readdirSync(worktrees, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+            .map((entry) => existingDirectory(path.join(worktrees, entry.name, '.agents', 'skills')))
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export function buildCanonicalSkillRoots(options = {}) {
+    const selectedCwd = normalizePath(options.selectedCwd);
+    const home = nativeHome(options);
+    const codexHome = normalizePath(options.codexHome || process.env.CODEX_HOME);
+    const claudeConfig = normalizePath(options.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR);
+    return uniquePaths([
+        ...projectRoots(selectedCwd),
+        home && path.join(home, '.agents', 'skills'),
+        codexHome && path.join(codexHome, 'skills'),
+        home && path.join(home, '.codex', 'skills'),
+        ...worktreeRoots(home),
+        claudeConfig && path.join(claudeConfig, 'skills'),
+        home && path.join(home, '.claude', 'skills'),
+        home && path.join(home, '.config', 'claude', 'skills'),
+        home && path.join(home, '.config', 'opencode', 'skills'),
+        home && path.join(home, '.opencode', 'skills'),
+    ]).filter(existingDirectory);
+}
+export function isCodexWorktreeRoot(rootPath, options = {}) {
+    const root = normalizePath(rootPath);
+    const home = nativeHome(options);
+    const worktrees = `${normalizePath(path.join(home, '.codex', 'worktrees'))}${path.sep}`;
+    return Boolean(root && home && root.startsWith(worktrees)
+        && root.endsWith(path.normalize(path.join('.agents', 'skills'))));
+}
+export function classifySkillRoot(rootPath, options = {}) {
+    const root = normalizePath(rootPath);
+    const selectedCwd = normalizePath(options.selectedCwd);
+    const home = nativeHome(options);
+    const codexHome = normalizePath(options.codexHome || process.env.CODEX_HOME);
+    const claudeConfig = normalizePath(options.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR);
+    if ((selectedCwd && root.startsWith(path.join(selectedCwd, '.agents', 'skills')))
+        || root.endsWith(path.normalize(path.join('.agents', 'skills')))) {
+        return { provider: 'shared', scope: 'project', rootLabel: 'Project skills' };
+    }
+    if (root === normalizePath(path.join(home, '.agents', 'skills'))) {
+        return { provider: 'shared', scope: 'global', rootLabel: 'Shared global skills' };
+    }
+    if ((codexHome && root === normalizePath(path.join(codexHome, 'skills')))
+        || root === normalizePath(path.join(home, '.codex', 'skills'))) {
+        return { provider: 'codex', scope: 'global', rootLabel: 'Codex skills' };
+    }
+    if ((claudeConfig && root === normalizePath(path.join(claudeConfig, 'skills')))
+        || root === normalizePath(path.join(home, '.claude', 'skills'))
+        || root === normalizePath(path.join(home, '.config', 'claude', 'skills'))) {
+        return { provider: 'claude_code', scope: 'global', rootLabel: 'Claude Code skills' };
+    }
+    if (root === normalizePath(path.join(home, '.config', 'opencode', 'skills'))
+        || root === normalizePath(path.join(home, '.opencode', 'skills'))) {
+        return { provider: 'opencode', scope: 'global', rootLabel: 'OpenCode skills' };
+    }
+    return { provider: 'shared', scope: 'global', rootLabel: 'Installed skills' };
+}

package/dist/skills/scanner.d.ts

@@ -0,0 +1,32 @@
+/** Installed-skill scanner from Engine `skills/scanner.js`. */
+import type { SkillRootOptions } from './roots.js';
+export interface InstalledSkill {
+    id: string;
+    name: string;
+    description: string;
+    content?: string;
+    contentHash?: string;
+    source: {
+        kind: 'installed';
+        provider: string;
+        scope: string;
+        rootLabel: string;
+        path: string;
+        directoryPath: string;
+        resolvedPath: string;
+        resolvedDirectoryPath: string;
+        rootPath: string;
+        viaSymlink: boolean;
+    };
+    updatedAt: string;
+    discoveredAt: string;
+}
+export interface SkillScanOptions extends SkillRootOptions {
+    includeContent?: boolean;
+    now?: () => string;
+}
+export declare function parseSkillFrontmatter(markdown: unknown): Record<string, string>;
+export declare function scanInstalledSkills(options?: SkillScanOptions): {
+    roots: string[];
+    skills: InstalledSkill[];
+};

package/dist/skills/scanner.js

@@ -0,0 +1,117 @@
+/** Installed-skill scanner from Engine `skills/scanner.js`. */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildCanonicalSkillRoots, classifySkillRoot, isCodexWorktreeRoot, normalizePath, } from './roots.js';
+const FRONTMATTER = /^---\s*\n([\s\S]*?)\n---/;
+function clean(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+function trimSlash(value) {
+    return value === path.sep ? value : value.replace(/[\\/]+$/, '');
+}
+export function parseSkillFrontmatter(markdown) {
+    const match = String(markdown || '').match(FRONTMATTER);
+    if (!match?.[1])
+        return {};
+    const fields = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const parts = line.match(/^\s*([A-Za-z0-9_-]+)\s*:\s*(.*?)\s*$/);
+        if (!parts?.[1])
+            continue;
+        let value = parts[2]?.trim() || '';
+        if ((value.startsWith('"') && value.endsWith('"'))
+            || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1);
+        fields[parts[1]] = value;
+    }
+    return fields;
+}
+function scanDirectory(root, name, options) {
+    const directory = path.join(root, name);
+    const file = path.join(directory, 'SKILL.md');
+    let stat;
+    try {
+        stat = fs.statSync(file);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    const content = fs.readFileSync(file, 'utf8');
+    const frontmatter = parseSkillFrontmatter(content);
+    const canonicalPath = normalizePath(file);
+    const classification = classifySkillRoot(root, options);
+    const skill = {
+        id: `skill-${crypto.createHash('sha256').update(canonicalPath).digest('hex').slice(0, 16)}`,
+        name: clean(frontmatter.name) || name,
+        description: clean(frontmatter.description),
+        source: {
+            kind: 'installed',
+            ...classification,
+            path: canonicalPath,
+            directoryPath: trimSlash(normalizePath(directory)),
+            resolvedPath: normalizePath(fs.realpathSync(file)),
+            resolvedDirectoryPath: trimSlash(fs.realpathSync(directory)),
+            rootPath: normalizePath(root),
+            viaSymlink: fs.lstatSync(directory).isSymbolicLink() || fs.lstatSync(file).isSymbolicLink(),
+        },
+        updatedAt: stat.mtime.toISOString(),
+        discoveredAt: options.now?.() || new Date().toISOString(),
+    };
+    if (options.includeContent) {
+        skill.content = content;
+        skill.contentHash = crypto.createHash('sha256').update(content).digest('hex');
+    }
+    return skill;
+}
+function entries(root) {
+    try {
+        return fs.readdirSync(root, { withFileTypes: true }).filter((entry) => {
+            if (entry.name.startsWith('.'))
+                return false;
+            if (entry.isDirectory())
+                return true;
+            if (!entry.isSymbolicLink())
+                return false;
+            try {
+                return fs.statSync(path.join(root, entry.name)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function scanInstalledSkills(options = {}) {
+    const roots = buildCanonicalSkillRoots(options);
+    const paths = new Set();
+    const resolved = new Set();
+    const signatures = new Set();
+    const skills = [];
+    for (const root of roots) {
+        for (const entry of entries(root)) {
+            const skill = scanDirectory(root, entry.name, { ...options, includeContent: true });
+            if (!skill || paths.has(skill.source.path) || resolved.has(skill.source.resolvedPath))
+                continue;
+            const signature = `${skill.name.toLowerCase()}::${skill.contentHash || ''}`;
+            if (isCodexWorktreeRoot(root, options) && signatures.has(signature))
+                continue;
+            paths.add(skill.source.path);
+            resolved.add(skill.source.resolvedPath);
+            signatures.add(signature);
+            if (!options.includeContent) {
+                delete skill.content;
+                delete skill.contentHash;
+            }
+            skills.push(skill);
+        }
+    }
+    skills.sort((left, right) => left.name.localeCompare(right.name)
+        || left.source.path.localeCompare(right.source.path));
+    return { roots, skills };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/agents",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local-first agent definitions, immutable revisions, and durable sessions.",
   "license": "UNLICENSED",
   "private": false,