@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/registry.js

@@ -1,6 +1,14 @@
+/**
+ * Package registry client -- search, resolve, and install from remote registries.
+ *
+ * Queries the MCP registry (registry.modelcontextprotocol.io) and future skill
+ * registries to find packages, then resolves them into installable entries
+ * with transport, runtime, and argument metadata.
+ */
 import * as fs from 'fs';
 import { DEFAULT_REGISTRIES } from './types.js';
 import { readMeta, writeMeta } from './state.js';
+/** Get all registries of a given type, merging defaults with user overrides. */
 export function getRegistries(type) {
     const meta = readMeta();
     const defaultRegs = DEFAULT_REGISTRIES[type] || {};
@@ -8,12 +16,14 @@ export function getRegistries(type) {
     // Merge defaults with user config (user overrides defaults)
     return { ...defaultRegs, ...userRegs };
 }
+/** Get only the enabled registries of a given type. */
 export function getEnabledRegistries(type) {
     const registries = getRegistries(type);
     return Object.entries(registries)
         .filter(([, config]) => config.enabled)
         .map(([name, config]) => ({ name, config }));
 }
+/** Add or update a registry configuration in agents.yaml. */
 export function setRegistry(type, name, config) {
     const meta = readMeta();
     if (!meta.registries) {
@@ -26,6 +36,7 @@ export function setRegistry(type, name, config) {
     meta.registries[type][name] = { ...existing, ...config };
     writeMeta(meta);
 }
+/** Remove a user-configured registry. Returns false if it did not exist. */
 export function removeRegistry(type, name) {
     const meta = readMeta();
     if (meta.registries?.[type]?.[name]) {
@@ -53,6 +64,7 @@ async function fetchMcpRegistry(url, query, limit = 20, apiKey) {
     }
     return response.json();
 }
+/** Search MCP registries for servers matching a query string. */
 export async function searchMcpRegistries(query, options) {
     const registries = getEnabledRegistries('mcp');
     const results = [];
@@ -86,6 +98,7 @@ export async function searchMcpRegistries(query, options) {
     }
     return results;
 }
+/** Look up detailed info for an MCP server by exact name. */
 export async function getMcpServerInfo(serverName, registryName) {
     const registries = getEnabledRegistries('mcp');
     const targetRegistries = registryName
@@ -108,16 +121,134 @@ export async function getMcpServerInfo(serverName, registryName) {
     }
     return null;
 }
-export async function searchSkillRegistries(_query, _options) {
+const skillIndexCache = new Map();
+const SKILL_INDEX_TTL_MS = 10 * 60_000;
+/** Fetch and cache a flat skill-index JSON document. */
+async function fetchSkillIndex(url, apiKey) {
+    const cached = skillIndexCache.get(url);
+    if (cached && Date.now() - cached.fetchedAt < SKILL_INDEX_TTL_MS) {
+        return cached.doc;
+    }
+    const headers = { Accept: 'application/json' };
+    if (apiKey)
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`Registry request failed: ${response.status} ${response.statusText}`);
+    }
+    const doc = (await response.json());
+    skillIndexCache.set(url, { fetchedAt: Date.now(), doc });
+    return doc;
+}
+/** Map a raw skill-index row into the canonical SkillEntry shape. */
+function normalizeSkillEntry(raw) {
+    return {
+        name: raw.name,
+        description: raw.description,
+        source: raw.source || 'unknown',
+        identifier: raw.identifier,
+        repo: raw.repo || undefined,
+        path: raw.path || undefined,
+        author: raw.author,
+        installs: raw.installs,
+        tags: raw.tags,
+        trustLevel: raw.trust_level,
+    };
+}
+/** Case-insensitive substring match against the fields users expect to search. */
+function skillMatchesQuery(entry, query) {
+    if (!query)
+        return true;
+    const q = query.toLowerCase();
+    const haystack = [
+        entry.name,
+        entry.identifier,
+        entry.description,
+        entry.source,
+        ...(entry.tags || []),
+    ]
+        .filter(Boolean)
+        .join(' ')
+        .toLowerCase();
+    return haystack.includes(q);
+}
+/** Search skill registries for entries matching a query string. */
+export async function searchSkillRegistries(query, options) {
     const registries = getEnabledRegistries('skill');
-    if (registries.length === 0) {
-        // No skill registries configured - this is expected for now
+    if (registries.length === 0)
+        return [];
+    const targetRegistries = options?.registry
+        ? registries.filter((r) => r.name === options.registry)
+        : registries;
+    if (targetRegistries.length === 0) {
+        if (options?.registry) {
+            throw new Error(`Registry '${options.registry}' not found or not enabled`);
+        }
         return [];
     }
-    // Future: implement skill registry API calls when available
-    // For now, skill: prefix falls back to git sources
-    return [];
+    const limit = options?.limit ?? 20;
+    const results = [];
+    for (const { name, config } of targetRegistries) {
+        try {
+            const doc = await fetchSkillIndex(config.url, config.apiKey);
+            for (const raw of doc.skills || []) {
+                const entry = normalizeSkillEntry(raw);
+                if (!skillMatchesQuery(entry, query))
+                    continue;
+                results.push({
+                    name: entry.identifier || entry.name,
+                    description: entry.description,
+                    type: 'skill',
+                    source: entry.source,
+                    registry: name,
+                    installs: entry.installs,
+                });
+                if (results.length >= limit)
+                    break;
+            }
+            if (results.length >= limit)
+                break;
+        }
+        catch (err) {
+            console.error(`Failed to search ${name}: ${err.message}`);
+        }
+    }
+    return results;
+}
+/** Look up a skill by identifier (or name) across enabled skill registries. */
+export async function getSkillEntry(skillIdentifier, registryName) {
+    const registries = getEnabledRegistries('skill');
+    const targets = registryName
+        ? registries.filter((r) => r.name === registryName)
+        : registries;
+    for (const { config } of targets) {
+        try {
+            const doc = await fetchSkillIndex(config.url, config.apiKey);
+            const match = (doc.skills || []).find((s) => s.identifier === skillIdentifier || s.name === skillIdentifier);
+            if (match)
+                return normalizeSkillEntry(match);
+        }
+        catch {
+            /* try next registry */
+        }
+    }
+    return null;
+}
+/** Derive a cloneable git source from a skill entry's repo/source metadata. */
+export function skillEntryToGitSource(entry) {
+    if (entry.repo) {
+        // Already an owner/repo; cloneRepo understands the `gh:` shorthand.
+        return `gh:${entry.repo.replace(/\.git$/, '')}`;
+    }
+    if (entry.source === 'official') {
+        // Hermes 'official' entries live in NousResearch/hermes-agent; the path
+        // sits under optional-skills/. cloneRepo pulls the whole repo — the
+        // per-path narrowing is a follow-on improvement.
+        return 'gh:NousResearch/hermes-agent';
+    }
+    return null;
 }
+/** Unified search across all enabled registries of the specified type(s). */
 export async function search(query, options) {
     const results = [];
     if (!options?.type || options.type === 'mcp') {
@@ -130,6 +261,7 @@ export async function search(query, options) {
     }
     return results;
 }
+/** Parse a package identifier into its type (mcp, skill, git) and name. */
 export function parsePackageIdentifier(identifier) {
     // mcp:filesystem -> MCP registry
     if (identifier.startsWith('mcp:')) {
@@ -161,6 +293,7 @@ export function parsePackageIdentifier(identifier) {
     // Single word -> search MCP registries first
     return { type: 'unknown', name: identifier };
 }
+/** Resolve a package identifier to an installable package with source metadata. */
 export async function resolvePackage(identifier) {
     const parsed = parsePackageIdentifier(identifier);
     if (parsed.type === 'git') {
@@ -178,7 +311,20 @@ export async function resolvePackage(identifier) {
         return null;
     }
     if (parsed.type === 'skill') {
-        // Skill registries not available yet, treat as git source
+        const entry = await getSkillEntry(parsed.name);
+        if (entry) {
+            const gitSource = skillEntryToGitSource(entry);
+            if (gitSource) {
+                return {
+                    type: 'skill',
+                    source: gitSource,
+                    skillEntry: entry,
+                };
+            }
+            // Entry found but has no installable repo (e.g. lobehub-only listings).
+            return null;
+        }
+        // Fall back to git shorthand when the identifier isn't in any registry.
         const gitSource = parsed.name.startsWith('gh:') ? parsed.name : `gh:${parsed.name}`;
         return { type: 'git', source: gitSource };
     }
@@ -200,4 +346,3 @@ export async function resolvePackage(identifier) {
     }
     return null;
 }
-//# sourceMappingURL=registry.js.map

package/dist/lib/resources.d.ts

@@ -4,19 +4,46 @@
  */
 import type { AgentId } from './types.js';
 import { type SkillParseError } from './skills.js';
+/** Resource kind — matches the subdirectory name under each repo root. */
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'profiles' | 'secrets';
+/** A resource resolved with its origin. */
+export interface ResolvedResource {
+    name: string;
+    /** Absolute path to the resource file or directory. */
+    path: string;
+    source: 'project' | 'user' | 'system';
+}
+/**
+ * Resolve a single resource by kind + name using project > user > system precedence.
+ * For file-based resources the path ends in `.md`, `.yaml`, or `.yml` as appropriate.
+ * Returns null when the resource does not exist in any scope.
+ *
+ * Extra repos are searched last (after system) to match syncResourcesToVersion order.
+ */
+export declare function resolveResource(kind: ResourceKind, name: string, cwd?: string): ResolvedResource | null;
+/**
+ * List all resources of a given kind across project, user, and system scopes.
+ * Returns a deduplicated union (project wins on name collision), each entry
+ * annotated with its origin source.
+ */
+export declare function listResources(kind: ResourceKind, cwd?: string): ResolvedResource[];
+/** A single installed resource (command, skill, memory file, or hook). */
 export interface ResourceEntry {
     name: string;
     path: string;
     scope: 'user' | 'project';
 }
+/** A skill resource entry with optional rule count. */
 export interface SkillResourceEntry extends ResourceEntry {
     ruleCount?: number;
 }
+/** An MCP server resource entry. */
 export interface McpResourceEntry {
     name: string;
     scope: 'user' | 'project';
     version?: string;
 }
+/** All resources installed for a specific agent. */
 export interface AgentResources {
     agentId: AgentId;
     commands: ResourceEntry[];
@@ -26,6 +53,7 @@ export interface AgentResources {
     memory: ResourceEntry[];
     hooks: ResourceEntry[];
 }
+/** Options for resource discovery. */
 export interface GetAgentResourcesOptions {
     cwd?: string;
     scope?: 'user' | 'project' | 'all';
@@ -47,4 +75,3 @@ export declare function getAllAgentResources(agentIds: AgentId[], options?: GetA
         installed: boolean;
     }>;
 }): AgentResources[];
-//# sourceMappingURL=resources.d.ts.map

package/dist/lib/resources.js

@@ -2,6 +2,8 @@
  * Unified resource discovery for agents.
  * Scans filesystem (source of truth) to find all installed resources for an agent.
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import { AGENTS, listInstalledMcpsWithScope } from './agents.js';
 import { listInstalledCommandsWithScope } from './commands.js';
 import { listInstalledSkillsWithScope } from './skills.js';
@@ -9,6 +11,83 @@ import { listInstalledHooksWithScope } from './hooks.js';
 import { listInstalledInstructionsWithScope } from './memory.js';
 import { getEffectiveHome } from './versions.js';
 import { listMcpServerConfigs } from './mcp.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
+/**
+ * Resolve a single resource by kind + name using project > user > system precedence.
+ * For file-based resources the path ends in `.md`, `.yaml`, or `.yml` as appropriate.
+ * Returns null when the resource does not exist in any scope.
+ *
+ * Extra repos are searched last (after system) to match syncResourcesToVersion order.
+ */
+export function resolveResource(kind, name, cwd) {
+    const projectDir = getProjectAgentsDir(cwd);
+    const extraRepos = getEnabledExtraRepos();
+    const candidates = [
+        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
+        [path.join(getUserAgentsDir(), kind), 'user'],
+        [path.join(getSystemAgentsDir(), kind), 'system'],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), 'system']),
+    ];
+    for (const [dir, source] of candidates) {
+        if (!fs.existsSync(dir))
+            continue;
+        // Try exact name (for directories like skills/subagents)
+        const exactPath = path.join(dir, name);
+        if (fs.existsSync(exactPath)) {
+            return { name, path: exactPath, source };
+        }
+        // Try with common file extensions
+        for (const ext of ['.md', '.yaml', '.yml']) {
+            const withExt = exactPath + ext;
+            if (fs.existsSync(withExt)) {
+                return { name, path: withExt, source };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * List all resources of a given kind across project, user, and system scopes.
+ * Returns a deduplicated union (project wins on name collision), each entry
+ * annotated with its origin source.
+ */
+export function listResources(kind, cwd) {
+    const seen = new Set();
+    const results = [];
+    const projectDir = getProjectAgentsDir(cwd);
+    const extraRepos = getEnabledExtraRepos();
+    const roots = [
+        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
+        [path.join(getUserAgentsDir(), kind), 'user'],
+        [path.join(getSystemAgentsDir(), kind), 'system'],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), 'system']),
+    ];
+    for (const [dir, source] of roots) {
+        if (!fs.existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const rawName = entry.name.replace(/\.(md|yaml|yml)$/, '');
+            if (seen.has(rawName))
+                continue;
+            seen.add(rawName);
+            results.push({
+                name: rawName,
+                path: path.join(dir, entry.name),
+                source,
+            });
+        }
+    }
+    return results;
+}
 /**
  * Get all resources installed for a specific agent by scanning the filesystem.
  * This is the source of truth - not the tracking data in agents.yaml.
@@ -100,4 +179,3 @@ export function getAllAgentResources(agentIds, options = {}) {
         return getAgentResources(agentId, { ...restOptions, cliInstalled });
     });
 }
-//# sourceMappingURL=resources.js.map

package/dist/lib/rotate.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Account rotation across agent versions.
+ *
+ * Detects which installed versions have expired credentials and rotates
+ * authentication tokens so users maintain active sessions across version switches.
+ */
+import type { AgentId, RunStrategy } from './types.js';
+import { type AccountInfo } from './agents.js';
+import { type UsageSnapshot } from './usage.js';
+export interface RotateCandidate {
+    agent: AgentId;
+    version: string;
+    email: string | null;
+    usageStatus: AccountInfo['usageStatus'];
+    usageSnapshot: UsageSnapshot | null;
+    authValid: boolean;
+    lastActive: Date | null;
+}
+export interface RotateResult {
+    /** The version picked for this run. */
+    picked: RotateCandidate;
+    /** Candidates that were considered healthy (including the picked one). */
+    healthy: RotateCandidate[];
+    /** Candidates excluded (not signed in, or out of credits). */
+    excluded: RotateCandidate[];
+}
+export declare const RUN_STRATEGIES: RunStrategy[];
+/**
+ * Return a run strategy when the input is valid, otherwise null.
+ *
+ * `'rotate'` is accepted as a deprecated alias for `'balanced'` so old yaml
+ * configs and `--strategy rotate` invocations keep working. The legacy alias
+ * normalizes to `'balanced'` and uses the weighted-random algorithm.
+ */
+export declare function normalizeRunStrategy(value: unknown): RunStrategy | null;
+/** Read project-local run strategy from the nearest agents.yaml, if present. */
+export declare function getProjectRunStrategy(agent: AgentId, startPath: string): RunStrategy | null;
+/** Resolve the configured strategy: project agents.yaml, then ~/.agents-system/agents.yaml, then pinned. */
+export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
+/** Persist the global run strategy used by bare `agents run <agent>`. */
+export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
+/**
+ * Pick a healthy candidate using weighted random by remaining capacity.
+ *
+ * Each healthy candidate gets weight = max(1, 100 - usedPercent) where
+ * usedPercent is the highest-utilized non-session window (week / sonnet_week
+ * for Claude). An account at 10% used gets weight 90; one at 90% used gets
+ * weight 10 — so the fresher account is 9× more likely to be picked. Over N
+ * calls, traffic distributes across healthy accounts proportional to their
+ * headroom, with no stampede on the lowest-usage one. Stateless — parallel
+ * callers naturally fan out via the random roll.
+ *
+ * Eligibility: signed in (email present), auth valid, and usage available
+ * (any non-session window strictly under 100%, or local flag not exhausted
+ * when no live snapshot exists).
+ *
+ * Dedupe: when multiple versions share an email, collapse to one candidate
+ * per email (the least-recently-active version). Prevents two parallel pods
+ * from "balancing" to different versions but hitting the same Anthropic
+ * account and both 429ing.
+ *
+ * Returns null if no candidate is eligible — callers fall back to the pinned
+ * version so behavior stays predictable.
+ */
+export declare function pickBalancedCandidate(candidates: RotateCandidate[]): RotateResult | null;
+/**
+ * Pick an available candidate. Prefers the configured pinned version when that
+ * version has usage available; otherwise routes to the candidate with the most
+ * usage headroom.
+ */
+export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
+/**
+ * Pick a healthy version for `agent` using weighted random by remaining
+ * capacity. See `pickBalancedCandidate` for algorithm details.
+ *
+ * No external state — health and capacity are both read off per-version
+ * AccountInfo (same data `agents view` surfaces). The weighted random roll
+ * keeps parallel callers fanned out without rotation files or locks.
+ *
+ * Returns null if no installed version is eligible. Callers fall back to the
+ * global default so behavior stays predictable — we never refuse to run.
+ */
+export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
+/** Select the configured version if available, otherwise another available version. */
+export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
+export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string): Promise<{
+    version: string | null;
+    rotation: RotateResult | null;
+}>;