@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/types.d.ts

@@ -1,5 +1,19 @@
+/**
+ * Core type definitions for agents-cli.
+ *
+ * Every data structure that flows between modules lives here: agent identity,
+ * configuration schemas, resource tracking, registry types, and permission
+ * formats for each supported agent.
+ */
+/** Unique identifier for a supported AI coding agent. */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo';
+/** How `agents run <agent>` chooses an installed version when none is pinned. */
+export type RunStrategy = 'pinned' | 'available' | 'rotate';
+/** Preview features that users can opt into via `agents beta`. */
+export type BetaFeatureName = 'drive' | 'factory';
+/** Subset of chalk color names used for agent-specific terminal output. */
 export type ChalkColor = 'magenta' | 'green' | 'blue' | 'cyan' | 'yellowBright' | 'redBright' | 'whiteBright' | 'blueBright' | 'greenBright' | 'magentaBright' | 'cyanBright';
+/** Static configuration for a single agent -- paths, capabilities, and format conventions. */
 export interface AgentConfig {
     id: AgentId;
     name: string;
@@ -19,12 +33,12 @@ export interface AgentConfig {
     supportsHooks: boolean;
     nativeAgentsSkillsDir?: boolean;
     capabilities: {
-        hooks: boolean;
-        mcp: boolean;
-        allowlist: boolean;
-        skills: boolean;
-        commands: boolean;
-        plugins: boolean;
+        hooks: Capability;
+        mcp: Capability;
+        allowlist: Capability;
+        skills: Capability;
+        commands: Capability;
+        plugins: Capability;
         /**
          * Whether the agent natively resolves `@path/to/file` imports inside its
          * memory file at session start. If false, agents-cli must pre-compile the
@@ -33,6 +47,29 @@ export interface AgentConfig {
         memoryImports?: boolean;
     };
 }
+/**
+ * A capability flag for an agent feature. `true` means supported on every
+ * installed version; `false` means never supported. The object form gates by
+ * semver: `since` is the minimum version that ships the feature, `until` is
+ * exclusive upper bound (set when a feature is removed in a later release).
+ */
+export type Capability = boolean | {
+    since?: string;
+    until?: string;
+};
+/** Names of every gateable capability on AgentConfig. */
+export type CapabilityName = 'hooks' | 'mcp' | 'allowlist' | 'skills' | 'commands' | 'plugins';
+/** Reason a capability check failed. */
+export type CapabilityFailReason = 'unsupported' | 'too_old' | 'too_new';
+/** Result of `supports(agent, cap, version?)`. */
+export type CapabilityResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: CapabilityFailReason;
+    need?: string;
+};
+/** Configuration for a single MCP server as stored in ~/.agents/mcp/. */
 export interface McpServerConfig {
     command?: string;
     url?: string;
@@ -43,24 +80,46 @@ export interface McpServerConfig {
     env?: Record<string, string>;
     headers?: Record<string, string>;
 }
+/** User-facing hook definition (name + script path). */
 export interface HookConfig {
     name: string;
     script: string;
     dataFile?: string;
 }
+/**
+ * Predicate set for declaring when a hook should fire within its declared event.
+ * All predicates AND together. Empty/missing matches: hook always fires.
+ */
+export interface HookMatches {
+    prompt_contains?: string;
+    prompt_matches?: string;
+    tool_name?: string | string[];
+    tool_args_match?: string;
+    git_dirty?: boolean;
+    cwd_includes?: string | string[];
+    project_has?: string;
+}
+/** Hook entry as declared in a package manifest (agents.yaml). */
 export interface ManifestHook {
     script: string;
     events: string[];
     timeout?: number;
     matcher?: string;
+    /** @deprecated Use the agent capability table; field is ignored. */
     agents?: AgentId[];
+    /** Set to false in user hooks.yaml to disable a system-shipped hook. */
+    enabled?: boolean;
+    /** Optional pre-filter predicates evaluated before invoking the script. */
+    matches?: HookMatches;
 }
+/** Lightweight hook descriptor used in resource listings. */
 export interface HookResourceEntry {
     name: string;
     events: string[];
     timeout?: number;
     matcher?: string;
 }
+/** A hook that has been synced into a specific agent version's config. */
 export interface InstalledHook {
     name: string;
     path: string;
@@ -68,8 +127,15 @@ export interface InstalledHook {
     scope: 'user' | 'project';
     agent: AgentId;
 }
+/** Package manifest (agents.yaml) found inside a cloned config repo or package. */
 export interface Manifest {
     agents?: Partial<Record<AgentId, string>>;
+    run?: Partial<Record<AgentId, {
+        strategy?: RunStrategy;
+    }>>;
+    beta?: {
+        enabled?: BetaFeatureName[];
+    };
     dependencies?: Record<string, string>;
     mcp?: Record<string, McpServerConfig>;
     defaults?: {
@@ -78,10 +144,12 @@ export interface Manifest {
         agents?: AgentId[];
     };
 }
+/** Record of how a slash command was installed into an agent version. */
 export interface CommandInstallation {
     path: string;
     method: 'symlink' | 'copy';
 }
+/** Metadata parsed from a SKILL.md frontmatter block. */
 export interface SkillMetadata {
     name: string;
     description: string;
@@ -90,15 +158,18 @@ export interface SkillMetadata {
     license?: string;
     keywords?: string[];
 }
+/** Record of how a skill was installed into an agent version. */
 export interface SkillInstallation {
     path: string;
     method: 'symlink' | 'copy';
 }
+/** Tracked state for a skill across all agent versions it's been synced to. */
 export interface SkillState {
     source: string;
     ruleCount: number;
     installations: Partial<Record<AgentId, SkillInstallation>>;
 }
+/** A skill that has been synced into a specific agent version's config. */
 export interface InstalledSkill {
     name: string;
     path: string;
@@ -107,22 +178,36 @@ export interface InstalledSkill {
     scope: 'user' | 'project';
     agent: AgentId;
 }
+/** Git remote metadata for the ~/.agents-system/ config repository. */
 export interface RepoInfo {
     source: string;
     branch: string;
     commit: string;
     lastSync: string;
 }
+/** Canonical system repo cloned into ~/.agents-system/. */
 export declare const DEFAULT_SYSTEM_REPO = "gh:phnx-labs/.agents";
+/** Previous system repo (personal fork), kept for migration detection. */
 export declare const LEGACY_SYSTEM_REPO = "gh:muqsitnawaz/.agents";
+/** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export declare function systemRepoSlug(repo?: string): string;
+/** Kind of package that can be searched and installed from a registry. */
 export type RegistryType = 'mcp' | 'skill';
+/** Connection details for a single package registry endpoint. */
 export interface RegistryConfig {
     url: string;
     enabled: boolean;
     apiKey?: string;
 }
+/** Built-in registry endpoints shipped with agents-cli. */
 export declare const DEFAULT_REGISTRIES: Record<RegistryType, Record<string, RegistryConfig>>;
+/**
+ * Registries that ship pre-seeded into new users' agents.yaml once, but are
+ * not "defaults" — after seeding they behave like any user-added registry
+ * (listable, disable-able, removable, and gone for good once removed).
+ */
+export declare const SEEDED_REGISTRIES: Record<RegistryType, Record<string, RegistryConfig>>;
+/** A single installable package within an MCP server entry. */
 export interface McpPackage {
     registry_name: string;
     name: string;
@@ -135,6 +220,7 @@ export interface McpPackage {
         required?: boolean;
     }>;
 }
+/** A server listing returned by the MCP registry API. */
 export interface McpServerEntry {
     name: string;
     description?: string;
@@ -149,6 +235,7 @@ export interface McpServerEntry {
     packages?: McpPackage[];
     _meta?: Record<string, unknown>;
 }
+/** Paginated response from the MCP registry search endpoint. */
 export interface McpRegistryResponse {
     servers: Array<{
         server: McpServerEntry;
@@ -158,15 +245,24 @@ export interface McpRegistryResponse {
         next_cursor?: string;
     };
 }
+/** A skill listing returned by a skill registry API. */
 export interface SkillEntry {
     name: string;
     description?: string;
+    /** Upstream catalog (e.g. 'official', 'github', 'lobehub', 'skills.sh'). */
     source: string;
+    /** Stable unique id used by the registry (e.g. 'official/security/1password'). */
+    identifier?: string;
+    /** Origin repo in 'owner/repo' form. Empty for registry-hosted catalogs. */
+    repo?: string;
     path?: string;
     author?: string;
     installs?: number;
     tags?: string[];
+    /** Registry-specific trust signal (e.g. 'builtin', 'trusted', 'community'). */
+    trustLevel?: string;
 }
+/** Paginated response from a skill registry search endpoint. */
 export interface SkillRegistryResponse {
     skills: SkillEntry[];
     metadata?: {
@@ -174,6 +270,7 @@ export interface SkillRegistryResponse {
         next_cursor?: string;
     };
 }
+/** Provider-agnostic search result that merges MCP and skill registries. */
 export interface RegistrySearchResult {
     name: string;
     description?: string;
@@ -183,13 +280,16 @@ export interface RegistrySearchResult {
     version?: string;
     installs?: number;
 }
+/** A package that has been resolved from a registry and is ready to install. */
 export interface ResolvedPackage {
     type: 'mcp' | 'skill' | 'git';
     source: string;
     mcpEntry?: McpServerEntry;
     skillEntry?: SkillEntry;
 }
+/** Categories of resources that can be synced into an agent version home. */
 export type ResourceType = 'commands' | 'skills' | 'hooks' | 'memory' | 'mcp' | 'permissions' | 'subagents' | 'plugins';
+/** Map of resource names synced to a specific agent version, keyed by type. */
 export interface VersionResources {
     commands?: string[];
     skills?: string[];
@@ -200,12 +300,14 @@ export interface VersionResources {
     subagents?: string[];
     plugins?: string[];
 }
+/** Manifest file (plugin.yaml) at the root of a plugin bundle. */
 export interface PluginManifest {
     name: string;
     description: string;
     version: string;
     agents?: AgentId[];
 }
+/** A plugin found on disk with its parsed manifest and resource inventory. */
 export interface DiscoveredPlugin {
     name: string;
     root: string;
@@ -214,12 +316,14 @@ export interface DiscoveredPlugin {
     hooks: string[];
     scripts: string[];
 }
+/** Frontmatter fields parsed from a subagent's agent.md file. */
 export interface SubagentFrontmatter {
     name: string;
     description: string;
     model?: string;
     color?: string;
 }
+/** A subagent definition found in ~/.agents/subagents/. */
 export interface DiscoveredSubagent {
     name: string;
     path: string;
@@ -227,18 +331,49 @@ export interface DiscoveredSubagent {
     agentMd: string;
     frontmatter: SubagentFrontmatter;
 }
+/** A subagent that has been synced into a specific agent version's config. */
 export interface InstalledSubagent {
     name: string;
     path: string;
     files: string[];
     frontmatter: SubagentFrontmatter;
 }
+/**
+ * Extra DotAgent repo registered as user-level config alongside ~/.agents/.
+ * Managed clones default to ~/.agents-<alias>/ as peer dirs; user-owned repos
+ * may live anywhere on disk via the `path` field. ~/.agents/ wins on name
+ * collisions; extras are searched in insertion order after the user repo.
+ */
+export interface ExtraRepoConfig {
+    url: string;
+    path?: string;
+    enabled: boolean;
+}
+/** Top-level structure of ~/.agents-system/agents.yaml -- the CLI's persistent state. */
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
+    run?: Partial<Record<AgentId, {
+        strategy?: RunStrategy;
+    }>>;
+    beta?: {
+        enabled?: BetaFeatureName[];
+    };
     registries?: Record<RegistryType, Record<string, RegistryConfig>>;
     versions?: Partial<Record<AgentId, Record<string, VersionResources>>>;
     source?: string;
-}
+    /**
+     * Extra DotAgent repos merged after ~/.agents/. Managed clones live as peer
+     * dirs at ~/.agents-<alias>/; user-owned repos can point at arbitrary paths
+     * via the `path` field.
+     */
+    extraRepos?: Record<string, ExtraRepoConfig>;
+    /**
+     * Keys like `skill.hermes` — registries seeded from SEEDED_REGISTRIES exactly
+     * once. Tracked so a user `registry remove` won't silently re-seed.
+     */
+    seededPresets?: string[];
+}
+/** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */
 export interface SyncOptions {
     agents?: AgentId[];
     yes?: boolean;
@@ -247,6 +382,7 @@ export interface SyncOptions {
     skipClis?: boolean;
     skipMcp?: boolean;
 }
+/** Agent-agnostic permission set (canonical format matches Claude's syntax). */
 export interface PermissionSet {
     name: string;
     description?: string;
@@ -254,11 +390,13 @@ export interface PermissionSet {
     deny?: string[];
     additionalDirectories?: string[];
 }
+/** A permission set that has been applied to a specific agent version. */
 export interface InstalledPermission {
     name: string;
     path: string;
     set: PermissionSet;
 }
+/** Claude's native settings.json permission format. */
 export interface ClaudePermissions {
     permissions: {
         allow: string[];
@@ -266,11 +404,13 @@ export interface ClaudePermissions {
         additionalDirectories?: string[];
     };
 }
+/** OpenCode's native permission format (per-command allow/deny/ask). */
 export interface OpenCodePermissions {
     permission: {
         bash: Record<string, 'allow' | 'deny' | 'ask'>;
     };
 }
+/** Codex's native permission format (approval policy + sandbox mode). */
 export interface CodexPermissions {
     approval_policy?: 'on-request' | 'on-failure' | 'never';
     sandbox_mode?: 'read-only' | 'workspace-write' | 'danger-full-access';
@@ -279,4 +419,3 @@ export interface CodexPermissions {
         writable_roots?: string[];
     };
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.js

@@ -1,8 +1,19 @@
+/**
+ * Core type definitions for agents-cli.
+ *
+ * Every data structure that flows between modules lives here: agent identity,
+ * configuration schemas, resource tracking, registry types, and permission
+ * formats for each supported agent.
+ */
+/** Canonical system repo cloned into ~/.agents-system/. */
 export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents';
+/** Previous system repo (personal fork), kept for migration detection. */
 export const LEGACY_SYSTEM_REPO = 'gh:muqsitnawaz/.agents';
+/** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
 export function systemRepoSlug(repo = DEFAULT_SYSTEM_REPO) {
     return repo.replace(/^gh:/, '').replace(/\.git$/, '');
 }
+/** Built-in registry endpoints shipped with agents-cli. */
 export const DEFAULT_REGISTRIES = {
     mcp: {
         official: {
@@ -10,9 +21,21 @@ export const DEFAULT_REGISTRIES = {
             enabled: true,
         },
     },
+    skill: {},
+};
+/**
+ * Registries that ship pre-seeded into new users' agents.yaml once, but are
+ * not "defaults" — after seeding they behave like any user-added registry
+ * (listable, disable-able, removable, and gone for good once removed).
+ */
+export const SEEDED_REGISTRIES = {
+    mcp: {},
     skill: {
-    // No public API available yet - skills.sh has no programmatic access
-    // When available: official: { url: 'https://api.skills.sh/v1', enabled: true }
+        // Hermes Agent (Nous Research) — flat JSON index of 1800+ skills aggregated
+        // from official, github, lobehub, skills.sh, and claude-marketplace. No auth.
+        hermes: {
+            url: 'https://hermes-agent.nousresearch.com/docs/api/skills-index.json',
+            enabled: true,
+        },
     },
 };
-//# sourceMappingURL=types.js.map

package/dist/lib/usage.d.ts

@@ -1,6 +1,8 @@
 import type { AccountInfo } from './agents.js';
 import type { AgentId } from './types.js';
+/** Discriminator for usage window types. */
 export type UsageWindowKey = 'session' | 'week' | 'sonnet_week';
+/** A single rate-limit window with utilization percentage and reset time. */
 export interface UsageWindow {
     key: UsageWindowKey;
     label: string;
@@ -9,33 +11,39 @@ export interface UsageWindow {
     resetsAt: Date | null;
     windowMinutes: number | null;
 }
+/** A point-in-time collection of usage windows from a single source. */
 export interface UsageSnapshot {
     source: 'live' | 'last_seen';
     sourceLabel: string;
     capturedAt: Date | null;
     windows: UsageWindow[];
 }
+/** Usage data plus any error encountered while fetching. */
 export interface UsageInfo {
     snapshot: UsageSnapshot | null;
     error: string | null;
 }
+/** Input needed to identify an account for usage lookup. */
 export interface UsageIdentityInput {
     agentId: AgentId;
     info: AccountInfo;
     home?: string;
     cliVersion?: string | null;
 }
+/** Options for fetching usage data. */
 interface UsageOptions {
     home?: string;
     cliVersion?: string | null;
     organizationId?: string | null;
 }
+/** Canonical input for a single usage fetch operation. */
 export interface UsageFetchInput {
     agentId: AgentId;
     home?: string;
     cliVersion: string | null;
     organizationId: string | null;
 }
+/** Claude OAuth credentials stored in the macOS Keychain. */
 interface ClaudeOauthCredentials {
     accessToken?: string | null;
     refreshToken?: string | null;
@@ -45,23 +53,47 @@ interface ClaudeOauthCredentials {
     rateLimitTier?: string | null;
     organizationUuid?: string | null;
 }
+/** Fetch usage info for a given agent, dispatching to the agent-specific implementation. */
 export declare function getUsageInfo(agentId: AgentId, options?: UsageOptions): Promise<UsageInfo>;
+/** Derive a stable lookup key from account info for usage deduplication. */
 export declare function getUsageLookupKey(info?: Pick<AccountInfo, 'usageKey' | 'accountKey'> | null): string | null;
+/**
+ * Deduplicate identity inputs into canonical (most-recently-active) accounts
+ * and build the corresponding fetch inputs for each unique usage key.
+ */
 export declare function buildCanonicalUsageContext(inputs: UsageIdentityInput[]): {
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageFetchInputs: Map<string, UsageFetchInput>;
 };
+/** Fetch usage info for all unique accounts in parallel, keyed by usage key. */
 export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Promise<{
     canonicalByUsageKey: Map<string, AccountInfo>;
     usageByKey: Map<string, UsageInfo>;
 }>;
+/**
+ * Fetch usage for a single identity, with a 2-minute cache fast path.
+ * Falls back to cached data when the live fetch fails.
+ */
 export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Promise<UsageInfo>;
+/** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
+/** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
+/** Load Claude OAuth credentials from the macOS Keychain. */
 export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
+/**
+ * Derive the Keychain service name for a Claude home directory.
+ * Managed (non-default) homes get a hash suffix for isolation.
+ */
 export declare function getClaudeKeychainService(home?: string): string;
+/**
+ * Check whether a requested org ID matches the live OAuth org ID.
+ * Returns true when either is absent (no filtering) or when they match.
+ */
 export declare function isClaudeUsageOrgMatch(requestedOrgId: string | null | undefined, liveOrgId: string | null | undefined): boolean;
+/** Read a cached usage snapshot for a given usage key. Returns null if absent or stale. */
 export declare function readClaudeUsageCache(usageKey: string, cachePath?: string, now?: Date): UsageSnapshot | null;
+/** Write a usage snapshot to the on-disk cache. */
 export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
 /**
  * Check whether the Claude OAuth credentials for a given home are usable.
@@ -70,4 +102,3 @@ export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageS
  */
 export declare function isClaudeAuthValid(home?: string): Promise<boolean>;
 export {};
-//# sourceMappingURL=usage.d.ts.map