@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/versions.d.ts

@@ -48,12 +48,35 @@ export declare function getAvailableResources(cwd?: string): AvailableResources;
 export declare function getActuallySyncedResources(agent: AgentId, version: string, options?: {
     cwd?: string;
 }): AvailableResources;
+/** Resource names that only exist in the project's `.agents/` layer, grouped by kind. */
+export interface ProjectOnlyResources {
+    commands: Set<string>;
+    skills: Set<string>;
+    hooks: Set<string>;
+    subagents: Set<string>;
+    plugins: Set<string>;
+    workflows: Set<string>;
+}
+/**
+ * Names that exist ONLY in the project's `.agents/` layer (no matching entry in
+ * user/system/extra layers). Sync intentionally skips project-layer commands,
+ * skills, hooks, subagents, plugins, and workflows for security — see the
+ * defense comments above each sync branch in syncResourcesToVersion. Without
+ * this filter, those names would forever appear in the "New resources" diff
+ * because they live in `available` but never reach `actuallySynced`.
+ */
+export declare function getProjectOnlyResources(cwd?: string): ProjectOnlyResources;
 /**
  * Compare available resources with what's ACTUALLY synced to version home.
  * Returns only NEW resources that haven't been synced yet.
  * Source of truth: the actual files/config, NOT agents.yaml tracking.
+ *
+ * `projectOnly` (recommended): the result of `getProjectOnlyResources(cwd)`.
+ * Names listed there are filtered out for kinds that sync intentionally
+ * excludes the project layer — otherwise they would re-appear as "new"
+ * on every run and "Yes, sync all new" would silently do nothing for them.
  */
-export declare function getNewResources(available: AvailableResources, actuallySynced: AvailableResources): AvailableResources;
+export declare function getNewResources(available: AvailableResources, actuallySynced: AvailableResources, projectOnly?: ProjectOnlyResources): AvailableResources;
 /**
  * Check if there are any new resources to sync.
  * When version is provided, uses version-specific capability checks.
@@ -63,7 +86,7 @@ export declare function hasNewResources(diff: AvailableResources, agent?: AgentI
  * Prompt user to select which NEW resources to sync.
  * Only shows resources that haven't been synced yet.
  */
-export declare function promptNewResourceSelection(agent: AgentId, newResources: AvailableResources): Promise<ResourceSelection | null>;
+export declare function promptNewResourceSelection(agent: AgentId, newResources: AvailableResources, version?: string): Promise<ResourceSelection | null>;
 /**
  * Prompt user to select which resources to sync from ~/.agents/.
  * Returns the selection, or null if user cancels.
@@ -118,7 +141,7 @@ export declare function listInstalledVersions(agent: AgentId): string[];
  * List every version directory for an agent, including ones missing the
  * binary (typically home-only leftovers from a prior `removeVersion`).
  *
- * Used by `agents prune` to surface stale installs that the regular
+ * Used by `agents prune cleanup` to surface stale installs that the regular
  * `listInstalledVersions` filters out. Do NOT use elsewhere — every other
  * call site assumes a working binary.
  */
@@ -163,6 +186,14 @@ export declare function softDeleteVersionDir(agent: AgentId, version: string): s
  * Nothing is hard-deleted.
  */
 export declare function removeVersion(agent: AgentId, version: string): boolean;
+/**
+ * Print the standard footer after one or more versions were soft-deleted to
+ * trash. Reminds the user that sessions stay readable and how to restore.
+ */
+export declare function printTrashFooter(moved: Array<{
+    agent: AgentId;
+    version: string;
+}>): void;
 /**
  * Remove all versions of an agent. Preserves each version's `home/` directory
  * so conversation history is never deleted; the per-version folders (now
@@ -277,6 +308,17 @@ export interface InstalledAgentTargetResult {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }
+/**
+ * Thrown when the user references an agent@version that is not installed.
+ * Carries the parsed (agentId, version) so callers can react — e.g. prompt
+ * to install it on demand — without having to parse the error message.
+ */
+export declare class VersionNotInstalledError extends Error {
+    readonly agentId: AgentId;
+    readonly version: string;
+    readonly installedVersions: readonly string[];
+    constructor(agentId: AgentId, version: string, installedVersions: readonly string[]);
+}
 /**
  * Resolve a comma-separated --agents list into concrete version selections.
  * Bare agents target the default version, or the newest installed version when no default exists.