@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/lib/profiles-presets.js

@@ -0,0 +1,103 @@
+/**
+ * Built-in profile presets for popular model providers.
+ *
+ * Each preset bundles a host CLI, API base URL, default model, and provider
+ * name so users can `agents profiles add kimi` without manual configuration.
+ */
+// Model IDs verified against openrouter.ai/api/v1/models on 2026-04-20.
+// Presets target the top-ranked open-source model per provider based on
+// SWE-bench Verified, LiveCodeBench, HumanEval, and Chatbot Arena rankings.
+//
+// Important limitation of Claude Code + non-Anthropic models via OpenRouter:
+// Claude Code sends `thinking:{type:"enabled"}` in its Anthropic payload by
+// default, and its `--print` consolidation returns empty text when a response
+// contains thinking/redacted_thinking blocks — even when the model *also*
+// emits a text block. This means reasoning models work fine in interactive
+// `claude` mode (same env vars) but `agents run <profile> --print` sees
+// empty stdout.
+//
+// Presets flagged "print-safe" use non-reasoning variants that ignore
+// thinking:enabled. Presets flagged "reasoning" are the leaderboard leaders
+// but are best invoked interactively.
+const OPENROUTER_BASE = 'https://openrouter.ai/api';
+const OPENROUTER_AUTH = {
+    provider: 'openrouter',
+    host: 'claude',
+    authEnvVar: 'ANTHROPIC_AUTH_TOKEN',
+    signupUrl: 'https://openrouter.ai/keys',
+};
+export const PRESETS = [
+    // ----- Top coding (via OpenRouter) -----
+    {
+        name: 'kimi',
+        description: 'Kimi K2.5 via OpenRouter (262K ctx, $0.38/$1.72 per 1M). Top Kimi: 99% HumanEval, 76.8% SWE-bench. REASONING — works interactively, but `agents run --print` returns empty stdout. Use `kimi-chat` preset for scripting.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'moonshotai/kimi-k2.5',
+            ANTHROPIC_SMALL_FAST_MODEL: 'moonshotai/kimi-k2.5',
+        },
+    },
+    {
+        name: 'kimi-chat',
+        description: 'Kimi K2 0905 via OpenRouter (262K ctx, $0.40/$2.00 per 1M). Non-reasoning sibling of K2.5 — slightly older but PRINT-SAFE, works end-to-end with `agents run --print` and in scripts/automation.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'moonshotai/kimi-k2-0905',
+            ANTHROPIC_SMALL_FAST_MODEL: 'moonshotai/kimi-k2-0905',
+        },
+    },
+    {
+        name: 'minimax',
+        description: 'MiniMax M2.5 via OpenRouter (230B params). #1 SWE-bench Verified (80.2%) on Apr 2026 leaderboards. REASONING — works interactively, --print returns empty.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'minimax/minimax-m2.5',
+            ANTHROPIC_SMALL_FAST_MODEL: 'minimax/minimax-m2.5',
+        },
+    },
+    {
+        name: 'glm',
+        description: 'GLM 5 via OpenRouter (80K ctx, $0.72/$2.30 per 1M). #1 Chatbot Arena ELO (1451) among open-weight models on BenchLM.ai (Apr 2026). Prompt-complexity-dependent reasoning — Claude Code\'s 38K system prompt typically triggers thinking blocks, so --print is unreliable. Interactive use is fine.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'z-ai/glm-5',
+            ANTHROPIC_SMALL_FAST_MODEL: 'z-ai/glm-5',
+        },
+    },
+    {
+        name: 'qwen',
+        description: 'Qwen3 Coder Next via OpenRouter (256K ctx, $0.15/$0.80 per 1M, sparse MoE 80B/3B active). Latest coding-specific Qwen (Feb 2026). PRINT-SAFE — works with `agents run --print`.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'qwen/qwen3-coder-next',
+            ANTHROPIC_SMALL_FAST_MODEL: 'qwen/qwen3-coder-next',
+        },
+    },
+    {
+        name: 'deepseek',
+        description: 'DeepSeek Chat V3 (0324) via OpenRouter. Latest DeepSeek Chat variant that ignores thinking:enabled. PRINT-SAFE. The newer V3.2 / V3.1-Terminus / V3.2-Speciale are reasoning variants — use `--model deepseek/deepseek-v3.2` to override if you want those for interactive use.',
+        ...OPENROUTER_AUTH,
+        env: {
+            ANTHROPIC_BASE_URL: OPENROUTER_BASE,
+            ANTHROPIC_MODEL: 'deepseek/deepseek-chat-v3-0324',
+            ANTHROPIC_SMALL_FAST_MODEL: 'deepseek/deepseek-chat-v3-0324',
+        },
+    },
+];
+/** Look up a preset by name (case-sensitive). */
+export function getPreset(name) {
+    return PRESETS.find((p) => p.name === name);
+}
+/** Return a copy of all available presets. */
+export function listPresets() {
+    return [...PRESETS];
+}
+/** Return the unique set of provider names across all presets. */
+export function listProviders() {
+    return [...new Set(PRESETS.map((p) => p.provider))];
+}

package/dist/lib/profiles.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Profile management -- named bundles of (host CLI, endpoint, model, auth).
+ *
+ * Profiles let users run agents against alternative providers (OpenRouter,
+ * custom endpoints) without reconfiguring the agent CLI itself. Stored as
+ * YAML files under ~/.agents/profiles/.
+ */
+import type { AgentId } from './types.js';
+import { type Preset } from './profiles-presets.js';
+/** A named profile binding an agent host, env vars, and optional keychain auth. */
+export interface Profile {
+    name: string;
+    host: {
+        agent: AgentId;
+        version?: string;
+    };
+    env: Record<string, string>;
+    auth?: {
+        envVar: string;
+        keychainItem: string;
+    };
+    description?: string;
+    preset?: string;
+    provider?: string;
+}
+/** Get the directory where profile YAML files are stored. */
+export declare function getProfilesDir(): string;
+/** Validate a profile name against the allowed pattern. Throws on invalid input. */
+export declare function validateProfileName(name: string): void;
+/** Check whether a profile YAML file exists on disk. */
+export declare function profileExists(name: string): boolean;
+/** Read and parse a profile from disk. Throws if not found or malformed. */
+export declare function readProfile(name: string): Profile;
+/** Write a profile to disk atomically (write-to-tmp then rename). */
+export declare function writeProfile(profile: Profile): void;
+/** Delete a profile from disk. Returns false if it did not exist. */
+export declare function deleteProfile(name: string): boolean;
+/** List all valid profiles, sorted by name. Malformed files are silently skipped. */
+export declare function listProfiles(): Profile[];
+/**
+ * Build a profile from a preset. The keychain item is shared across all
+ * profiles that point at the same provider, so adding kimi + deepseek prompts
+ * for the OpenRouter key exactly once.
+ */
+export declare function profileFromPreset(profileName: string, preset: Preset, version?: string): Profile;
+/**
+ * Resolve a profile into the env block that should be injected into the
+ * spawned agent process. Reads the token from keychain at exec time so the
+ * profile YAML never holds secrets.
+ */
+export declare function resolveProfileEnv(profile: Profile): Record<string, string>;
+/** Resolved profile data ready for spawning an agent process. */
+export interface ResolvedProfileRun {
+    agent: AgentId;
+    version?: string;
+    env: Record<string, string>;
+    profileName: string;
+}
+/**
+ * Resolve a name into (agent, version, env). Throws if the name is not a
+ * profile. Callers are expected to try agent-id resolution first and fall
+ * back to this when that fails, so we don't need a "isProfile" probe.
+ */
+export declare function resolveProfileForRun(name: string): ResolvedProfileRun;
+/**
+ * Look up the preset a profile was created from, if any. Used by
+ * `profiles view` to show upstream metadata like signup URLs.
+ */
+export declare function getPresetForProfile(profile: Profile): Preset | undefined;

package/dist/lib/profiles.js

@@ -0,0 +1,144 @@
+/**
+ * Profile management -- named bundles of (host CLI, endpoint, model, auth).
+ *
+ * Profiles let users run agents against alternative providers (OpenRouter,
+ * custom endpoints) without reconfiguring the agent CLI itself. Stored as
+ * YAML files under ~/.agents/profiles/.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+import { getKeychainToken, keychainItemName } from './secrets/profiles.js';
+import { getPreset } from './profiles-presets.js';
+const PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
+/** Get the directory where profile YAML files are stored. */
+export function getProfilesDir() {
+    return path.join(getUserAgentsDir(), 'profiles');
+}
+function profilePath(name) {
+    return path.join(getProfilesDir(), `${name}.yml`);
+}
+/** Validate a profile name against the allowed pattern. Throws on invalid input. */
+export function validateProfileName(name) {
+    if (!PROFILE_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid profile name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
+    }
+}
+/** Check whether a profile YAML file exists on disk. */
+export function profileExists(name) {
+    return fs.existsSync(profilePath(name));
+}
+/** Read and parse a profile from disk. Throws if not found or malformed. */
+export function readProfile(name) {
+    validateProfileName(name);
+    const file = profilePath(name);
+    if (!fs.existsSync(file)) {
+        throw new Error(`Profile '${name}' not found.`);
+    }
+    const raw = fs.readFileSync(file, 'utf-8');
+    const parsed = yaml.parse(raw);
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`Profile '${name}' is malformed.`);
+    }
+    if (!parsed.name)
+        parsed.name = name;
+    if (!parsed.host?.agent) {
+        throw new Error(`Profile '${name}' is missing host.agent.`);
+    }
+    if (!parsed.env || typeof parsed.env !== 'object') {
+        parsed.env = {};
+    }
+    return parsed;
+}
+/** Write a profile to disk atomically (write-to-tmp then rename). */
+export function writeProfile(profile) {
+    validateProfileName(profile.name);
+    const dir = getProfilesDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const body = yaml.stringify(profile);
+    const file = profilePath(profile.name);
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, body, 'utf-8');
+    fs.renameSync(tmp, file);
+}
+/** Delete a profile from disk. Returns false if it did not exist. */
+export function deleteProfile(name) {
+    validateProfileName(name);
+    const file = profilePath(name);
+    if (!fs.existsSync(file))
+        return false;
+    fs.unlinkSync(file);
+    return true;
+}
+/** List all valid profiles, sorted by name. Malformed files are silently skipped. */
+export function listProfiles() {
+    const dir = getProfilesDir();
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    const profiles = [];
+    for (const entry of entries) {
+        const name = entry.replace(/\.(yml|yaml)$/, '');
+        try {
+            profiles.push(readProfile(name));
+        }
+        catch {
+            // Skip malformed profile files; surfacing via `agents profiles view <name>`.
+        }
+    }
+    return profiles.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Build a profile from a preset. The keychain item is shared across all
+ * profiles that point at the same provider, so adding kimi + deepseek prompts
+ * for the OpenRouter key exactly once.
+ */
+export function profileFromPreset(profileName, preset, version) {
+    return {
+        name: profileName,
+        host: { agent: preset.host, version },
+        env: { ...preset.env },
+        auth: {
+            envVar: preset.authEnvVar,
+            keychainItem: keychainItemName(preset.provider),
+        },
+        description: preset.description,
+        preset: preset.name,
+        provider: preset.provider,
+    };
+}
+/**
+ * Resolve a profile into the env block that should be injected into the
+ * spawned agent process. Reads the token from keychain at exec time so the
+ * profile YAML never holds secrets.
+ */
+export function resolveProfileEnv(profile) {
+    const env = { ...profile.env };
+    if (profile.auth) {
+        const token = getKeychainToken(profile.auth.keychainItem);
+        env[profile.auth.envVar] = token;
+    }
+    return env;
+}
+/**
+ * Resolve a name into (agent, version, env). Throws if the name is not a
+ * profile. Callers are expected to try agent-id resolution first and fall
+ * back to this when that fails, so we don't need a "isProfile" probe.
+ */
+export function resolveProfileForRun(name) {
+    const profile = readProfile(name);
+    return {
+        agent: profile.host.agent,
+        version: profile.host.version,
+        env: resolveProfileEnv(profile),
+        profileName: profile.name,
+    };
+}
+/**
+ * Look up the preset a profile was created from, if any. Used by
+ * `profiles view` to show upstream metadata like signup URLs.
+ */
+export function getPresetForProfile(profile) {
+    return profile.preset ? getPreset(profile.preset) : undefined;
+}

package/dist/lib/pty-client.d.ts

@@ -4,6 +4,7 @@
  * Thin client that connects to the PTY sidecar server over unix socket.
  * Each call opens a connection, sends a JSON request, reads the JSON response, and closes.
  */
+/** JSON response envelope from the PTY server. */
 export interface PtyResponse {
     ok: boolean;
     error?: string;
@@ -19,4 +20,3 @@ export declare function ptyRequest(action: string, id?: string, params?: Record<
  * Handles: \n \r \t \e \xHH \\
  */
 export declare function unescapeInput(input: string): string;
-//# sourceMappingURL=pty-client.d.ts.map

package/dist/lib/pty-client.js

@@ -178,4 +178,3 @@ export function unescapeInput(input) {
         }
     });
 }
-//# sourceMappingURL=pty-client.js.map

package/dist/lib/pty-server.d.ts

@@ -6,11 +6,25 @@
  * across multiple CLI invocations. Each session holds a real PTY (via node-pty)
  * and a headless terminal emulator (via @xterm/headless) for screen rendering.
  *
- * Protocol: newline-delimited JSON over ~/.agents/pty.sock
+ * Protocol: newline-delimited JSON over ~/.agents-system/pty.sock
  */
+/**
+ * Capture a stable identifier for a process at the moment it was started.
+ * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
+ * still occupies the PID we observed at spawn time.
+ *
+ * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
+ * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
+ * Returns null on any error so callers can skip the guard rather than crash.
+ */
+export declare function captureProcessStartTime(pid: number): string | null;
+/** Get the unix socket path for the PTY server. */
 export declare function getSocketPath(): string;
+/** Get the path to the PTY server PID file. */
 export declare function getPtyPidPath(): string;
+/** Get the path to the PTY server log file. */
 export declare function getPtyLogPath(): string;
+/** Check if the PTY server process is alive by probing the stored PID. */
 export declare function isPtyServerRunning(): boolean;
+/** Start the PTY sidecar server, listening on the unix socket for JSON requests. */
 export declare function runPtyServer(): Promise<void>;
-//# sourceMappingURL=pty-server.d.ts.map

package/dist/lib/pty-server.js

@@ -6,14 +6,51 @@
  * across multiple CLI invocations. Each session holds a real PTY (via node-pty)
  * and a headless terminal emulator (via @xterm/headless) for screen rendering.
  *
- * Protocol: newline-delimited JSON over ~/.agents/pty.sock
+ * Protocol: newline-delimited JSON over ~/.agents-system/pty.sock
  */
 import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
+import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getAgentsDir } from './state.js';
+/**
+ * Capture a stable identifier for a process at the moment it was started.
+ * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
+ * still occupies the PID we observed at spawn time.
+ *
+ * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
+ * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
+ * Returns null on any error so callers can skip the guard rather than crash.
+ */
+export function captureProcessStartTime(pid) {
+    if (!pid || pid <= 0)
+        return null;
+    try {
+        if (process.platform === 'linux') {
+            const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+            // The comm field (#2) is wrapped in parens and may contain spaces, so
+            // split off everything after the last `)` to get a clean field list.
+            const lastParen = stat.lastIndexOf(')');
+            if (lastParen < 0)
+                return null;
+            const tail = stat.slice(lastParen + 2);
+            const fields = tail.split(' ');
+            // After comm we are at field 3; starttime is field 22, so index 19 here.
+            return fields[19] || null;
+        }
+        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const trimmed = out.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
 // --- Constants ---
 const SENTINEL = '__AGENTS_PTY_DONE__';
 const SOCKET_NAME = 'pty.sock';
@@ -22,15 +59,39 @@ const LOG_FILE = 'pty.log';
 const SESSION_IDLE_MS = 30 * 60 * 1000; // 30 min
 const SERVER_IDLE_MS = 60 * 60 * 1000; // 1 hour
 // --- Path helpers ---
+/** Env vars forwarded into PTY sessions. Excludes API tokens, cloud creds, etc. */
+const PTY_ENV_ALLOWLIST = [
+    'HOME', 'PATH', 'SHELL', 'USER', 'LOGNAME',
+    'TERM', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION', 'COLORTERM',
+    'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', 'TZ',
+    'TMPDIR',
+    'XDG_RUNTIME_DIR', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME',
+    'NODE_PATH', 'NVM_DIR', 'BUN_INSTALL',
+    'EDITOR', 'VISUAL', 'PAGER', 'LESS',
+    'NO_COLOR', 'FORCE_COLOR',
+];
+function buildPtyEnv() {
+    const env = {};
+    for (const key of PTY_ENV_ALLOWLIST) {
+        const v = process.env[key];
+        if (v !== undefined)
+            env[key] = v;
+    }
+    return env;
+}
+/** Get the unix socket path for the PTY server. */
 export function getSocketPath() {
     return path.join(getAgentsDir(), SOCKET_NAME);
 }
+/** Get the path to the PTY server PID file. */
 export function getPtyPidPath() {
     return path.join(getAgentsDir(), PID_FILE);
 }
+/** Get the path to the PTY server log file. */
 export function getPtyLogPath() {
     return path.join(getAgentsDir(), LOG_FILE);
 }
+/** Check if the PTY server process is alive by probing the stored PID. */
 export function isPtyServerRunning() {
     const pidPath = getPtyPidPath();
     if (!fs.existsSync(pidPath))
@@ -60,6 +121,7 @@ function log(level, message) {
     catch { }
 }
 // --- Server ---
+/** Start the PTY sidecar server, listening on the unix socket for JSON requests. */
 export async function runPtyServer() {
     // Dynamic imports for optional native deps
     let nodePty;
@@ -177,7 +239,7 @@ export async function runPtyServer() {
                         cols,
                         rows,
                         cwd,
-                        env: { ...process.env },
+                        env: buildPtyEnv(),
                     });
                 }
                 catch (err) {
@@ -193,6 +255,7 @@ export async function runPtyServer() {
                     shell,
                     cwd,
                     pid: ptyProcess.pid,
+                    startTime: captureProcessStartTime(ptyProcess.pid),
                     startedAt: Date.now(),
                     lastActivity: Date.now(),
                     pendingOutput: '',
@@ -308,6 +371,18 @@ export async function runPtyServer() {
                 if (!['INT', 'TERM', 'KILL', 'HUP'].includes(sig)) {
                     return { ok: false, error: `Unsupported signal: ${sig}` };
                 }
+                // Guard against PID reuse: confirm the PID is still owned by the
+                // process we spawned. If the start-time we captured at spawn no
+                // longer matches /proc or `ps`, treat the session as exited and
+                // refuse to signal — otherwise we'd kill an unrelated process that
+                // happens to have inherited this PID.
+                if (session.startTime !== null) {
+                    const current = captureProcessStartTime(session.pid);
+                    if (current === null || current !== session.startTime) {
+                        session.exited = true;
+                        return { ok: false, error: 'Session has exited' };
+                    }
+                }
                 try {
                     // node-pty kill accepts signal number; use process.kill for named signals
                     process.kill(session.pid, `SIG${sig}`);
@@ -389,9 +464,24 @@ export async function runPtyServer() {
         });
         conn.on('error', () => { });
     });
+    // Lock down ~/.agents-system/ before opening the socket — without this, any local
+    // user with execute on the parent dir could connect to the socket during
+    // the listen()-to-chmod() window. macOS BSD AF_UNIX semantics make socket
+    // mode advisory only, so the parent dir is the real boundary.
+    const agentsDir = getAgentsDir();
+    fs.mkdirSync(agentsDir, { recursive: true });
+    fs.chmodSync(agentsDir, 0o700);
+    // umask covers any inherited group/other bits while listen() is creating
+    // the socket inode — it only matters for the unobservable instant before
+    // we can chmod the inode itself.
+    process.umask(0o077);
     await new Promise((resolve) => {
         server.listen(socketPath, () => resolve());
     });
+    // Surface chmod failures: a 0o600 socket is a load-bearing security
+    // assumption, not a nice-to-have. If we can't lock it down, refuse to
+    // start so the caller learns immediately.
+    fs.chmodSync(socketPath, 0o600);
     // Write PID
     fs.writeFileSync(getPtyPidPath(), String(process.pid), 'utf-8');
     log('INFO', `PTY server started (PID: ${process.pid}, socket: ${socketPath})`);
@@ -419,4 +509,3 @@ export async function runPtyServer() {
     // Keep alive
     await new Promise(() => { });
 }
-//# sourceMappingURL=pty-server.js.map

package/dist/lib/registry.d.ts

@@ -1,28 +1,48 @@
-import type { RegistryType, RegistryConfig, McpServerEntry, RegistrySearchResult, ResolvedPackage } from './types.js';
+/**
+ * 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 type { RegistryType, RegistryConfig, McpServerEntry, SkillEntry, RegistrySearchResult, ResolvedPackage } from './types.js';
+/** Get all registries of a given type, merging defaults with user overrides. */
 export declare function getRegistries(type: RegistryType): Record<string, RegistryConfig>;
+/** Get only the enabled registries of a given type. */
 export declare function getEnabledRegistries(type: RegistryType): Array<{
     name: string;
     config: RegistryConfig;
 }>;
+/** Add or update a registry configuration in agents.yaml. */
 export declare function setRegistry(type: RegistryType, name: string, config: Partial<RegistryConfig>): void;
+/** Remove a user-configured registry. Returns false if it did not exist. */
 export declare function removeRegistry(type: RegistryType, name: string): boolean;
+/** Search MCP registries for servers matching a query string. */
 export declare function searchMcpRegistries(query: string, options?: {
     registry?: string;
     limit?: number;
 }): Promise<RegistrySearchResult[]>;
+/** Look up detailed info for an MCP server by exact name. */
 export declare function getMcpServerInfo(serverName: string, registryName?: string): Promise<McpServerEntry | null>;
-export declare function searchSkillRegistries(_query: string, _options?: {
+/** Search skill registries for entries matching a query string. */
+export declare function searchSkillRegistries(query: string, options?: {
     registry?: string;
     limit?: number;
 }): Promise<RegistrySearchResult[]>;
+/** Look up a skill by identifier (or name) across enabled skill registries. */
+export declare function getSkillEntry(skillIdentifier: string, registryName?: string): Promise<SkillEntry | null>;
+/** Derive a cloneable git source from a skill entry's repo/source metadata. */
+export declare function skillEntryToGitSource(entry: SkillEntry): string | null;
+/** Unified search across all enabled registries of the specified type(s). */
 export declare function search(query: string, options?: {
     type?: RegistryType;
     registry?: string;
     limit?: number;
 }): Promise<RegistrySearchResult[]>;
+/** Parse a package identifier into its type (mcp, skill, git) and name. */
 export declare function parsePackageIdentifier(identifier: string): {
     type: RegistryType | 'git' | 'unknown';
     name: string;
 };
+/** Resolve a package identifier to an installable package with source metadata. */
 export declare function resolvePackage(identifier: string): Promise<ResolvedPackage | null>;
-//# sourceMappingURL=registry.d.ts.map